agentic-kdd 3.2.2 → 3.3.1

package/autonomous-decision.cjs

@@ -0,0 +1,735 @@
+/**
+ * Agentic KDD — Autonomous Decision Engine v1.0
+ *
+ * Motor de decisión autónoma L4.
+ *
+ * Lo que resuelve:
+ *   - El agente detecta situaciones que afectan lo que se está trabajando
+ *     y decide autónomamente si implementar, advertir, o diferir
+ *   - Prerequisite chain: detecta si algo que hay que tocar tiene un
+ *     prerequisito roto y lo resuelve primero
+ *   - Cross-module pattern: si el mismo error ya ocurrió en otro módulo
+ *     y fue resuelto allá, aplica la misma solución aquí
+ *   - Full spectrum: no solo mira errores — también protege lo que funciona
+ *
+ * Decisiones posibles:
+ *   STOP              → blast CRITICAL o PROTECTED contract roto
+ *                        No implementar. Reportar exactamente qué rompería.
+ *   WARN              → blast HIGH o VERIFIED contract en riesgo
+ *                        Implementar pero avisar. El dev decide si continuar.
+ *   IMPLEMENT         → blast MEDIUM/LOW + sin rotura de contratos
+ *                        Implementar ahora dentro del ciclo.
+ *   IMPLEMENT_CAUTIOUS→ prerequisito resuelto primero, luego la tarea
+ *                        Implementar en orden: prerequisito → tarea original
+ *   DEFER             → blast LOW + sin historial + sin contratos en riesgo
+ *                        No tocar ahora. Agregar a cola de sugerencias al final.
+ *
+ * Uso desde el pipeline (harness.cjs lo llama automáticamente):
+ *   const { analyze } = require('./autonomous-decision.cjs');
+ *   const decision = await analyze({ files: ['src/auth.ts'], task: 'fix session' });
+ *
+ * Uso manual:
+ *   node autonomous-decision.cjs analyze src/auth.ts
+ *   node autonomous-decision.cjs queue           — ver cola diferida
+ *   node autonomous-decision.cjs flush           — mostrar cola y limpiarla
+ */
+
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+// ─── CONSTANTES ───────────────────────────────────────────────────────────────
+
+const DECISIONS = {
+  STOP:               'STOP',
+  WARN:               'WARN',
+  IMPLEMENT:          'IMPLEMENT',
+  IMPLEMENT_CAUTIOUS: 'IMPLEMENT_CAUTIOUS',
+  DEFER:              'DEFER',
+};
+
+const BLAST_LEVELS = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
+
+const DEFERRED_QUEUE_PATH = '.agentic/deferred_queue.json';
+
+// ─── DB ───────────────────────────────────────────────────────────────────────
+
+function openDB(projectRoot) {
+  const dbPath = path.join(projectRoot, '.agentic/memoria.db');
+  try { return new (require('better-sqlite3'))(dbPath); } catch {}
+  try { const { DatabaseSync } = require('node:sqlite'); return new DatabaseSync(dbPath); } catch {}
+  return null;
+}
+
+function safe(fn, fallback = null) {
+  try { return fn(); } catch { return fallback; }
+}
+
+// ─── PREREQUISITE CHAIN DETECTION ────────────────────────────────────────────
+/**
+ * Dado un set de archivos a modificar, detecta si algún prerequisito
+ * en la cadena de dependencias tiene contratos rotos.
+ *
+ * Ejemplo:
+ *   Quieres tocar dashboard.ts
+ *   dashboard.ts importa authMiddleware.ts
+ *   authMiddleware.ts tiene contrato INVALIDATED
+ *   → authMiddleware.ts es prerequisito roto
+ */
+function detectPrerequisiteChain(db, targetFiles, projectRoot) {
+  const broken = [];
+
+  if (!db) return broken;
+
+  targetFiles.forEach(file => {
+    const basename = path.basename(file);
+
+    // Obtener dependencias via AST edges
+    const deps = safe(() =>
+      db.prepare(`
+        SELECT DISTINCT hacia_entidad as dep
+        FROM relaciones_semanticas
+        WHERE (desde_entidad LIKE ? OR desde_entidad = ?)
+          AND tipo IN ('depende_de', 'importa', 'usa', 'llama')
+          AND (invalid_at IS NULL OR invalid_at = '')
+        LIMIT 20
+      `).all(`%${basename}%`, file)
+    ) || [];
+
+    deps.forEach(({ dep }) => {
+      if (!dep) return;
+
+      // Verificar si esa dependencia tiene contratos fallidos o invalidados
+      const brokenContracts = safe(() =>
+        db.prepare(`
+          SELECT id, name, status, module
+          FROM verified_contracts
+          WHERE (test_file LIKE ? OR name LIKE ? OR module LIKE ?)
+            AND status IN ('invalidated')
+          LIMIT 5
+        `).all(`%${dep}%`, `%${dep}%`, `%${path.basename(dep, path.extname(dep))}%`)
+      ) || [];
+
+      if (brokenContracts.length > 0) {
+        broken.push({
+          prerequisite: dep,
+          broken_contracts: brokenContracts,
+          affects: file,
+          reason: `${dep} has ${brokenContracts.length} broken contract(s) — must be fixed before ${basename}`,
+        });
+      }
+
+      // También verificar errores HIGH confidence no resueltos en la dependencia
+      const depArea = path.basename(dep, path.extname(dep)).toLowerCase();
+      const unresolvedErrors = safe(() =>
+        db.prepare(`
+          SELECT titulo, confianza FROM nodos
+          WHERE tipo = 'error'
+            AND confianza IN ('ALTA', 'MEDIA')
+            AND estado = 'ACTIVO'
+            AND area LIKE ?
+            AND (vigencia_tipo = 'VIGENTE' OR vigencia_tipo IS NULL)
+          LIMIT 3
+        `).all(`%${depArea}%`)
+      ) || [];
+
+      if (unresolvedErrors.length > 0 && brokenContracts.length === 0) {
+        broken.push({
+          prerequisite: dep,
+          broken_contracts: [],
+          unresolved_errors: unresolvedErrors,
+          affects: file,
+          reason: `${dep} has ${unresolvedErrors.length} HIGH/MEDIUM unresolved error(s)`,
+          severity: 'soft', // no es STOP, es WARN
+        });
+      }
+    });
+  });
+
+  return broken;
+}
+
+// ─── CROSS-MODULE ERROR CHECK ─────────────────────────────────────────────────
+/**
+ * ¿Este error ya ocurrió en otro módulo?
+ * Si sí y fue resuelto → propone misma solución
+ * Si sí y no fue resuelto → es sistémico, escalar
+ */
+function crossModuleCheck(db, errorSignatures, currentFiles) {
+  if (!db || !errorSignatures || errorSignatures.length === 0) return [];
+
+  const findings = [];
+  const currentAreas = currentFiles.map(f => path.basename(f, path.extname(f)).toLowerCase());
+
+  errorSignatures.forEach(sig => {
+    if (!sig) return;
+
+    // Buscar el mismo error en otras áreas
+    const otherInstances = safe(() =>
+      db.prepare(`
+        SELECT id, titulo, area, contenido, aplicado
+        FROM nodos
+        WHERE tipo = 'error'
+          AND (titulo LIKE ? OR contenido LIKE ?)
+          AND estado = 'ACTIVO'
+          AND area NOT IN (${currentAreas.map(() => '?').join(',')})
+        ORDER BY aplicado DESC
+        LIMIT 5
+      `).all(`%${sig}%`, `%${sig}%`, ...currentAreas)
+    ) || [];
+
+    otherInstances.forEach(inst => {
+      // ¿Fue resuelto allá?
+      const fixEdge = safe(() =>
+        db.prepare(`
+          SELECT descripcion, hacia_entidad
+          FROM relaciones_semanticas
+          WHERE desde_entidad LIKE ?
+            AND tipo = 'was_fixed_by'
+            AND (invalid_at IS NULL OR invalid_at = '')
+          LIMIT 1
+        `).get(`%${inst.area}%`)
+      );
+
+      findings.push({
+        signature:   sig,
+        found_in:    inst.area,
+        titulo:      inst.titulo,
+        was_fixed:   !!fixEdge,
+        fix_applied: fixEdge?.descripcion || null,
+        fix_target:  fixEdge?.hacia_entidad || null,
+        is_systemic: !fixEdge,
+        recommendation: fixEdge
+          ? `Apply same fix as in ${inst.area}: ${fixEdge.descripcion?.substring(0, 80)}`
+          : `Systemic error — also present in ${inst.area} without resolution. Escalate priority.`,
+      });
+    });
+  });
+
+  return findings;
+}
+
+// ─── BLAST RADIUS CHECK ───────────────────────────────────────────────────────
+
+function getBlastLevel(db, targetFiles) {
+  if (!db) return { level: 'LOW', level_int: 0, contracts_at_risk: 0, protected: 0 };
+
+  let contractsAtRisk = 0;
+  let protectedAtRisk = 0;
+
+  try {
+    const allContracts = db.prepare(
+      "SELECT * FROM verified_contracts WHERE status IN ('protected','verified')"
+    ).all();
+
+    targetFiles.forEach(file => {
+      const basename = path.basename(file);
+      allContracts.forEach(c => {
+        const testFile = c.test_file || '';
+        const isAtRisk = testFile.includes(basename) ||
+          (c.module && file.toLowerCase().includes(c.module.toLowerCase()));
+        if (isAtRisk) {
+          contractsAtRisk++;
+          if (c.status === 'protected') protectedAtRisk++;
+        }
+      });
+    });
+  } catch {}
+
+  const level = contractsAtRisk === 0   ? 'LOW'
+    : contractsAtRisk <= 3              ? 'LOW'
+    : contractsAtRisk <= 10             ? 'MEDIUM'
+    : contractsAtRisk <= 20             ? 'HIGH'
+    : 'CRITICAL';
+
+  return {
+    level,
+    level_int: BLAST_LEVELS[level],
+    contracts_at_risk: contractsAtRisk,
+    protected: protectedAtRisk,
+  };
+}
+
+// ─── DEFERRED QUEUE ───────────────────────────────────────────────────────────
+
+function loadDeferredQueue(projectRoot) {
+  const qPath = path.join(projectRoot, DEFERRED_QUEUE_PATH);
+  if (!fs.existsSync(qPath)) return [];
+  try { return JSON.parse(fs.readFileSync(qPath, 'utf8')); } catch { return []; }
+}
+
+function saveDeferredQueue(projectRoot, queue) {
+  const qPath = path.join(projectRoot, DEFERRED_QUEUE_PATH);
+  try { fs.writeFileSync(qPath, JSON.stringify(queue, null, 2)); } catch {}
+}
+
+function addToDeferred(projectRoot, item) {
+  const queue = loadDeferredQueue(projectRoot);
+  queue.push({ ...item, deferred_at: new Date().toISOString() });
+  // Máx 50 items en cola
+  if (queue.length > 50) queue.splice(0, queue.length - 50);
+  saveDeferredQueue(projectRoot, queue);
+}
+
+function flushDeferredQueue(projectRoot) {
+  const queue = loadDeferredQueue(projectRoot);
+  if (queue.length === 0) return [];
+  saveDeferredQueue(projectRoot, []);
+  return queue;
+}
+
+// ─── MOTOR DE DECISIÓN PRINCIPAL ─────────────────────────────────────────────
+/**
+ * Analiza un cambio propuesto y decide qué hacer.
+ *
+ * @param {Object} params
+ * @param {string[]} params.files          Archivos a modificar
+ * @param {string}   params.task           Descripción de la tarea
+ * @param {string[]} params.errorSignatures Firmas de errores detectados (opcional)
+ * @param {string}   params.projectRoot
+ */
+function analyze(params = {}) {
+  const {
+    files          = [],
+    task           = '',
+    errorSignatures= [],
+    projectRoot    = process.cwd(),
+  } = params;
+
+  const db = openDB(projectRoot);
+  const result = {
+    decision:     DECISIONS.IMPLEMENT,
+    files,
+    task,
+    blast:        null,
+    prerequisites: [],
+    cross_module:  [],
+    reasons:       [],
+    deferred:      [],
+    action_plan:   [],
+    summary:       '',
+  };
+
+  // ── 1. BLAST RADIUS ────────────────────────────────────────────────────────
+  if (files.length > 0) {
+    result.blast = getBlastLevel(db, files);
+
+    if (result.blast.protected > 0) {
+      // Hay contratos PROTECTED en riesgo → STOP
+      result.decision = DECISIONS.STOP;
+      result.reasons.push(
+        `PROTECTED contracts at risk: ${result.blast.protected}. ` +
+        `These represent verified behavior that must not break.`
+      );
+    } else if (result.blast.level === 'CRITICAL') {
+      result.decision = DECISIONS.STOP;
+      result.reasons.push(
+        `Blast radius CRITICAL: ${result.blast.contracts_at_risk} contracts at risk. ` +
+        `Too many verified behaviors could break.`
+      );
+    } else if (result.blast.level === 'HIGH') {
+      result.decision = DECISIONS.WARN;
+      result.reasons.push(
+        `Blast radius HIGH: ${result.blast.contracts_at_risk} contracts at risk. ` +
+        `Proceed with caution. Run akdd contracts gate after changes.`
+      );
+    }
+  }
+
+  // ── 2. PREREQUISITE CHAIN ──────────────────────────────────────────────────
+  if (files.length > 0 && result.decision !== DECISIONS.STOP) {
+    const prereqs = detectPrerequisiteChain(db, files, projectRoot);
+    const hardPrereqs = prereqs.filter(p => !p.severity || p.severity === 'hard');
+    const softPrereqs = prereqs.filter(p => p.severity === 'soft');
+
+    if (hardPrereqs.length > 0) {
+      result.prerequisites = hardPrereqs;
+      result.decision = DECISIONS.IMPLEMENT_CAUTIOUS;
+      result.reasons.push(
+        `Prerequisite chain broken: ${hardPrereqs.length} dependency(ies) have broken contracts. ` +
+        `Must fix prerequisites first.`
+      );
+      result.action_plan = [
+        ...hardPrereqs.map(p => ({
+          step: 'FIX_PREREQUISITE',
+          target: p.prerequisite,
+          reason: p.reason,
+          before_main_task: true,
+        })),
+        { step: 'EXECUTE_ORIGINAL_TASK', target: files, task },
+      ];
+    } else if (softPrereqs.length > 0) {
+      result.prerequisites = softPrereqs;
+      if (result.decision === DECISIONS.IMPLEMENT) {
+        result.decision = DECISIONS.WARN;
+      }
+      result.reasons.push(
+        `Soft prerequisite warning: ${softPrereqs.length} dependency(ies) have unresolved HIGH errors.`
+      );
+    }
+  }
+
+  // ── 3. CROSS-MODULE CHECK ──────────────────────────────────────────────────
+  if (errorSignatures.length > 0) {
+    const crossModuleFindings = crossModuleCheck(db, errorSignatures, files);
+    result.cross_module = crossModuleFindings;
+
+    const systemicErrors = crossModuleFindings.filter(f => f.is_systemic);
+    const fixableErrors  = crossModuleFindings.filter(f => f.was_fixed);
+
+    if (systemicErrors.length > 0 && result.decision === DECISIONS.IMPLEMENT) {
+      result.decision = DECISIONS.WARN;
+      result.reasons.push(
+        `Systemic error detected: ${systemicErrors.length} error(s) also present in other modules ` +
+        `without resolution. Consider addressing root cause.`
+      );
+    }
+
+    if (fixableErrors.length > 0) {
+      result.reasons.push(
+        `Cross-module pattern found: ${fixableErrors.length} error(s) were already ` +
+        `resolved in other modules. Applying same fix pattern.`
+      );
+      result.action_plan.push(
+        ...fixableErrors.map(f => ({
+          step: 'APPLY_KNOWN_FIX',
+          signature: f.signature,
+          from_module: f.found_in,
+          fix: f.fix_applied,
+        }))
+      );
+    }
+  }
+
+  // ── 4. LOW BLAST + SIN HISTORIAL → DEFER ──────────────────────────────────
+  if (result.decision === DECISIONS.IMPLEMENT &&
+      result.blast?.level === 'LOW' &&
+      result.cross_module.length === 0 &&
+      result.prerequisites.length === 0 &&
+      files.length > 0) {
+
+    // ¿Hay historial causal para estos archivos?
+    let hasHistory = false;
+    if (db) {
+      files.forEach(f => {
+        const basename = path.basename(f);
+        const history = safe(() =>
+          db.prepare(`
+            SELECT COUNT(*) as n FROM relaciones_semanticas
+            WHERE (desde_entidad LIKE ? OR hacia_entidad LIKE ?)
+              AND tipo IN ('caused_failure', 'was_fixed_by', 'regressed_by')
+              AND (invalid_at IS NULL OR invalid_at = '')
+          `).get(`%${basename}%`, `%${basename}%`)?.n
+        ) || 0;
+        if (history > 0) hasHistory = true;
+      });
+    }
+
+    if (!hasHistory && task && task.toLowerCase().includes('minor')) {
+      // Solo diferir si explícitamente se indica que es menor
+      result.decision = DECISIONS.DEFER;
+      result.deferred = files;
+      addToDeferred(projectRoot, { files, task, reason: 'Low blast, no history, minor scope' });
+      result.reasons.push('Low blast radius, no causal history, minor scope — deferred to end-of-cycle suggestions.');
+    }
+  }
+
+  // ── 5. RESUMEN EJECUTIVO ───────────────────────────────────────────────────
+  result.summary = buildSummary(result);
+
+  if (db) { try { db.close(); } catch {} }
+  return result;
+}
+
+// ─── RESUMEN EJECUTIVO ────────────────────────────────────────────────────────
+
+function buildSummary(result) {
+  const icons = {
+    STOP:               '🛑',
+    WARN:               '⚠️',
+    IMPLEMENT:          '✅',
+    IMPLEMENT_CAUTIOUS: '🔄',
+    DEFER:              '📋',
+  };
+
+  const icon = icons[result.decision] || '?';
+  let summary = `${icon} Decision: ${result.decision}`;
+
+  if (result.blast) {
+    summary += ` | Blast: ${result.blast.level} (${result.blast.contracts_at_risk} contracts)`;
+  }
+
+  if (result.prerequisites.length > 0) {
+    summary += ` | Prerequisites: ${result.prerequisites.length} broken`;
+  }
+
+  if (result.cross_module.length > 0) {
+    const fixed = result.cross_module.filter(f => f.was_fixed).length;
+    const systemic = result.cross_module.filter(f => f.is_systemic).length;
+    if (fixed > 0) summary += ` | ${fixed} known fix(es) available`;
+    if (systemic > 0) summary += ` | ${systemic} systemic error(s)`;
+  }
+
+  return summary;
+}
+
+// ─── PRINT RESULT ─────────────────────────────────────────────────────────────
+
+function printAnalysis(result) {
+  console.log('\n' + '═'.repeat(60));
+  console.log('  Autonomous Decision Engine');
+  console.log('═'.repeat(60));
+  console.log(`\n  ${result.summary}\n`);
+
+  if (result.reasons.length > 0) {
+    console.log('  Reasons:');
+    result.reasons.forEach(r => console.log(`    • ${r}`));
+    console.log('');
+  }
+
+  if (result.prerequisites.length > 0) {
+    console.log('  Prerequisite chain:');
+    result.prerequisites.forEach(p => {
+      console.log(`    ⚡ ${p.prerequisite}`);
+      console.log(`       ${p.reason}`);
+    });
+    console.log('');
+  }
+
+  if (result.cross_module.length > 0) {
+    console.log('  Cross-module findings:');
+    result.cross_module.forEach(f => {
+      const icon = f.was_fixed ? '✅' : '⚠️';
+      console.log(`    ${icon} "${f.signature}" also in ${f.found_in}`);
+      console.log(`       ${f.recommendation}`);
+    });
+    console.log('');
+  }
+
+  if (result.action_plan.length > 0) {
+    console.log('  Action plan:');
+    result.action_plan.forEach((step, i) => {
+      console.log(`    ${i + 1}. [${step.step}] ${step.target || step.signature || ''}`);
+      if (step.reason) console.log(`       Reason: ${step.reason}`);
+      if (step.fix) console.log(`       Apply: ${step.fix}`);
+    });
+    console.log('');
+  }
+
+  console.log('═'.repeat(60) + '\n');
+}
+
+// ─── SPRINT PLANNER ───────────────────────────────────────────────────────────
+/**
+ * Punto 3: Sprint planning con contexto explícito del dev.
+ *
+ * El dev pasa el contexto una vez. Agentic cruza contra datos técnicos.
+ * Produce un plan ejecutable por prioridad real (negocio + técnica).
+ *
+ * @param {Object} context
+ * @param {string} context.objective      "Terminar el módulo de pagos antes del viernes"
+ * @param {string[]} context.constraints  ["no tocar auth.ts esta semana"]
+ * @param {string[]} context.priorities   ["pagos bloquea al cliente X"]
+ * @param {string} projectRoot
+ */
+function planSprint(context = {}, projectRoot) {
+  projectRoot = projectRoot || process.cwd();
+  const db = openDB(projectRoot);
+  if (!db) return { error: 'DB no disponible' };
+
+  const { objective = '', constraints = [], priorities = [] } = context;
+
+  const plan = {
+    objective,
+    constraints,
+    business_priorities: priorities,
+    technical_findings:  [],
+    combined_priority:   [],
+    sprint_blocks:       [],
+  };
+
+  // Detectar deuda técnica por blast radius
+  try {
+    const highRisk = db.prepare(`
+      SELECT DISTINCT module, COUNT(*) as contract_count
+      FROM verified_contracts
+      WHERE status IN ('invalidated', 'verified')
+        AND failure_count > 0
+      GROUP BY module
+      ORDER BY failure_count DESC, contract_count DESC
+      LIMIT 10
+    `).all();
+
+    plan.technical_findings = highRisk.map(r => ({
+      module:    r.module,
+      contracts: r.contract_count,
+      priority:  r.contract_count > 5 ? 'HIGH' : r.contract_count > 2 ? 'MEDIUM' : 'LOW',
+    }));
+  } catch {}
+
+  // Errores sin resolver de alta confianza
+  try {
+    const unresolvedErrors = db.prepare(`
+      SELECT area, COUNT(*) as n, MAX(confianza) as max_conf
+      FROM nodos
+      WHERE tipo = 'error'
+        AND estado = 'ACTIVO'
+        AND confianza IN ('ALTA', 'MEDIA')
+      GROUP BY area
+      ORDER BY n DESC
+      LIMIT 8
+    `).all();
+
+    unresolvedErrors.forEach(e => {
+      plan.technical_findings.push({
+        module:   e.area,
+        errors:   e.n,
+        priority: e.max_conf === 'ALTA' ? 'HIGH' : 'MEDIUM',
+        type:     'unresolved_errors',
+      });
+    });
+  } catch {}
+
+  // Combinar prioridad de negocio con prioridad técnica
+  const businessKeywords = [...priorities, objective].join(' ').toLowerCase();
+
+  plan.technical_findings.forEach(f => {
+    const moduleStr = (f.module || '').toLowerCase();
+    const businessMatch = businessKeywords.includes(moduleStr) ||
+      priorities.some(p => p.toLowerCase().includes(moduleStr));
+
+    const isConstrained = constraints.some(c =>
+      c.toLowerCase().includes(moduleStr)
+    );
+
+    plan.combined_priority.push({
+      module:           f.module,
+      technical_priority: f.priority,
+      business_match:   businessMatch,
+      constrained:      isConstrained,
+      final_priority:   isConstrained ? 'BLOCKED'
+        : businessMatch && f.priority === 'HIGH' ? 'P1_CRITICAL'
+        : businessMatch ? 'P2_HIGH'
+        : f.priority === 'HIGH' ? 'P3_MEDIUM'
+        : 'P4_LOW',
+    });
+  });
+
+  // Ordenar plan
+  const order = { P1_CRITICAL:0, P2_HIGH:1, P3_MEDIUM:2, P4_LOW:3, BLOCKED:4 };
+  plan.combined_priority.sort((a, b) =>
+    (order[a.final_priority] || 3) - (order[b.final_priority] || 3)
+  );
+
+  // Bloques del sprint
+  plan.sprint_blocks = [
+    {
+      block: 'Immediate — P1/P2',
+      items: plan.combined_priority.filter(p => ['P1_CRITICAL','P2_HIGH'].includes(p.final_priority)),
+    },
+    {
+      block: 'This cycle — P3',
+      items: plan.combined_priority.filter(p => p.final_priority === 'P3_MEDIUM'),
+    },
+    {
+      block: 'Next cycle — P4',
+      items: plan.combined_priority.filter(p => p.final_priority === 'P4_LOW'),
+    },
+    {
+      block: 'BLOCKED — do not touch',
+      items: plan.combined_priority.filter(p => p.final_priority === 'BLOCKED'),
+    },
+  ].filter(b => b.items.length > 0);
+
+  if (db) { try { db.close(); } catch {} }
+  return plan;
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const [,, cmd, ...args] = process.argv;
+  const projectRoot = process.cwd();
+
+  switch (cmd) {
+    case 'analyze': {
+      const files = args.filter(a => !a.startsWith('--'));
+      const result = analyze({ files, task: args.join(' '), projectRoot });
+      printAnalysis(result);
+      process.exit(result.decision === DECISIONS.STOP ? 1 : 0);
+    }
+
+    case 'queue': {
+      const queue = loadDeferredQueue(projectRoot);
+      if (queue.length === 0) {
+        console.log('\n  Cola diferida vacía.\n');
+      } else {
+        console.log(`\n  Cola diferida (${queue.length} items):\n`);
+        queue.forEach((item, i) => {
+          console.log(`  ${i+1}. [${item.deferred_at?.split('T')[0]}] ${item.task}`);
+          console.log(`     Files: ${(item.files || []).join(', ')}`);
+        });
+        console.log('');
+      }
+      break;
+    }
+
+    case 'flush': {
+      const flushed = flushDeferredQueue(projectRoot);
+      if (flushed.length === 0) {
+        console.log('\n  Sin items diferidos.\n');
+      } else {
+        console.log(`\n  ${flushed.length} items de la cola para revisar:\n`);
+        flushed.forEach((item, i) => {
+          console.log(`  ${i+1}. ${item.task}`);
+          if (item.reason) console.log(`     ${item.reason}`);
+        });
+        console.log('');
+      }
+      break;
+    }
+
+    case 'sprint': {
+      // Uso: node autonomous-decision.cjs sprint --objective "..." --priority "..." --constraint "..."
+      const getArg = (flag) => {
+        const idx = process.argv.indexOf(flag);
+        return idx >= 0 ? process.argv[idx + 1] : null;
+      };
+      const objective   = getArg('--objective') || 'Complete current sprint tasks';
+      const priorities  = process.argv.filter((_, i) => process.argv[i-1] === '--priority');
+      const constraints = process.argv.filter((_, i) => process.argv[i-1] === '--constraint');
+
+      const plan = planSprint({ objective, priorities, constraints }, projectRoot);
+
+      if (plan.error) { console.log(`\n  Error: ${plan.error}\n`); break; }
+
+      console.log('\n  Sprint Plan\n  ' + '─'.repeat(40));
+      console.log(`  Objective: ${plan.objective}\n`);
+
+      plan.sprint_blocks.forEach(block => {
+        console.log(`  ${block.block}:`);
+        block.items.forEach(item => {
+          const marker = item.business_match ? '★' : '○';
+          console.log(`    ${marker} ${item.module} [${item.final_priority}]`);
+        });
+        console.log('');
+      });
+      break;
+    }
+
+    default:
+      console.log('Uso: node autonomous-decision.cjs [analyze <files> | queue | flush | sprint --objective "..."]');
+  }
+}
+
+module.exports = {
+  analyze,
+  planSprint,
+  detectPrerequisiteChain,
+  crossModuleCheck,
+  getBlastLevel,
+  loadDeferredQueue,
+  flushDeferredQueue,
+  DECISIONS,
+};

package/bin/akdd.js

@@ -66,6 +66,15 @@ const HELP = `
     akdd creative apply <id>   Apply a suggestion
     akdd creative wins         View applied creative improvements
 
+  Autonomous decisions (L4):
+    akdd decide <file>     Analyze a change — STOP/WARN/IMPLEMENT/DEFER decision
+    akdd deferred          View deferred queue (end-of-cycle suggestions)
+    akdd deferred flush    Show and clear deferred queue
+    akdd sprint-plan "obj" Generate sprint plan from business objective
+
+  Effectiveness:
+    akdd report            Real data — before vs after comparison across all cycles
+
   Session continuity:
     akdd historial         Resume context in a new chat — paste output at start
     akdd checkpoint        Save checkpoint now (auto-runs every 5 cycles)
@@ -267,6 +276,30 @@ switch (command) {
     break;
   }
 
+  // ── v3.3: Autonomous Decision Engine ──────────────────────────────────────
+  case 'decide': {
+    const files = args.slice(1);
+    if (!files.length) { console.log('\n  Uso: akdd decide <archivo> [archivos...]\n'); break; }
+    runModule('autonomous-decision.cjs', 'analyze', files.map(f => `"${f}"`).join(' '));
+    break;
+  }
+  case 'deferred': {
+    const sub = arg1 || 'queue';
+    runModule('autonomous-decision.cjs', sub === 'flush' ? 'flush' : 'queue');
+    break;
+  }
+  case 'sprint-plan': {
+    const objective = args.slice(1).join(' ');
+    if (!objective) { console.log('\n  Uso: akdd sprint-plan "objetivo del sprint"\n'); break; }
+    runModule('autonomous-decision.cjs', 'sprint', `--objective "${objective}"`);
+    break;
+  }
+
+  // ── v3.3: Effectiveness Report ──────────────────────────────────────────────
+  case 'report':
+    runModule('effectiveness-report.cjs');
+    break;
+
   // ── v3.3: Session Guard ────────────────────────────────────────────────────
   case 'historial':
     runModule('session-guard.cjs', 'historial');

package/collab-manager.cjs

@@ -26,13 +26,42 @@ const PROVISIONER_URL = 'https://agentic-collab.adrianlpz-game.workers.dev';
 
 const COLLAB_CONFIG_PATH = '.agentic/collab.json';
 
+// ─── SYNC TABLES — TODO lo que hace a Agentic L4 ──────────────────────────────
+// Regla: si está aquí, cualquier miembro del equipo que haga collab pull
+// recibe el cerebro completo del proyecto — no solo fragmentos.
+//
+// NO sincronizar:
+//   regression_snapshots  → snapshots de sesión individual, no conocimiento del equipo
+//   working_memory        → buffer de sesión activa, se resetea por diseño
+//   creative_suggestions  → sugerencias personales del dev, no del equipo
+//   git_context_log       → log local de diffs, cada dev tiene su propio git
+//   deferred_queue        → archivo JSON por dev, no tabla compartida
+//
 const SYNC_TABLES = [
-  'nodos',
-  'relaciones_semanticas',
-  'episodios',
-  'knowledge_docs',
-  'ast_symbols',
-  'ast_edges',
+
+  // ── CORE MEMORY (CoALA 4 layers) ───────────────────────────────────────────
+  'nodos',              // Patrones, errores, decisiones con confianza — EL núcleo
+  'episodios',          // Historia cruda de cada ciclo
+  'entidades',          // Módulos, archivos, APIs detectados en el proyecto
+  'relaciones_semanticas', // Causal edges: caused_failure, was_fixed_by, verifies, protects
+
+  // ── CICLOS Y TRAZABILIDAD ──────────────────────────────────────────────────
+  'ciclos',             // Qué se hizo, cuándo, con qué resultado — historial ejecutivo
+  'fases',              // Fases dentro de cada ciclo — granularidad total
+  'knowledge_docs',     // ADRs, gotchas, convenciones — por qué las cosas son como son
+
+  // ── AST GRAPH ─────────────────────────────────────────────────────────────
+  'ast_symbols',        // Símbolos del codebase — estructura completa
+  'ast_edges',          // Relaciones AST — dependencias, imports, call graph
+
+  // ── PRESERVATION INTELLIGENCE ─────────────────────────────────────────────
+  'verified_contracts', // Contratos protegidos — lo que no se puede romper
+  'creative_wins',      // Mejoras aplicadas — el equipo aprende de lo que funcionó
+  'contract_violations',// Violaciones pasadas — el equipo sabe qué rompió qué
+
+  // ── PREDICCIÓN Y CI/CD ────────────────────────────────────────────────────
+  'prediction_log',     // Patrones de riesgo predictivo detectados
+  'cicd_reports',       // Reportes de CI/CD — qué falló en producción
 ];
 
 // ─── DB LOCAL ──────────────────────────────────────────────────────────────────
@@ -346,9 +375,14 @@ async function syncDown(projectRoot) {
         const placeholders = keys.map(() => '?').join(', ');
 
         // Estrategia por tabla:
-        // episodios → INSERT OR IGNORE (son aditivos, no sobrescribir locales)
-        // resto     → INSERT OR REPLACE (toma la versión más reciente)
-        const strategy = table === 'episodios' ? 'OR IGNORE' : 'OR REPLACE';
+        // OR IGNORE: tablas aditivas — no sobrescribir versión local
+        //   episodios, ciclos, fases, prediction_log, cicd_reports
+        //   (cada dev tiene su propia historia de ejecución)
+        // OR REPLACE: tablas de conocimiento compartido — toma la más reciente
+        //   nodos, entidades, relaciones_semanticas, knowledge_docs,
+        //   ast_symbols, ast_edges, verified_contracts, creative_wins, contract_violations
+        const ADDITIVE_TABLES = new Set(['episodios','ciclos','fases','prediction_log','cicd_reports']);
+        const strategy = ADDITIVE_TABLES.has(table) ? 'OR IGNORE' : 'OR REPLACE';
 
         try {
           localDB.prepare(
@@ -420,12 +454,25 @@ async function status(projectRoot) {
 
 function getDateField(table) {
   const fields = {
-    nodos: 'fecha_update',
-    episodios: 'fecha',
-    relaciones_semanticas: 'valid_at',
-    knowledge_docs: 'last_indexed',
-    ast_symbols: 'last_indexed',
-    ast_edges: 'last_indexed',
+    // Core memory
+    nodos:                  'fecha_update',
+    episodios:              'fecha',
+    entidades:              'fecha_update',
+    relaciones_semanticas:  'valid_at',
+    // Ciclos y trazabilidad
+    ciclos:                 'fecha_inicio',
+    fases:                  'fecha',
+    knowledge_docs:         'last_indexed',
+    // AST
+    ast_symbols:            'last_indexed',
+    ast_edges:              'last_indexed',
+    // Preservation Intelligence
+    verified_contracts:     'updated_at',
+    creative_wins:          'created_at',
+    contract_violations:    'created_at',
+    // Predicción y CI/CD
+    prediction_log:         'fecha',
+    cicd_reports:           'fecha',
   };
   return fields[table] || 'rowid';
 }

package/effectiveness-report.cjs

@@ -0,0 +1,402 @@
+/**
+ * Agentic KDD — Effectiveness Report v1.0
+ *
+ * Genera datos reales de efectividad comparando primeros ciclos vs últimos.
+ * Todo viene de SQLite — cero estimaciones, cero inventados.
+ *
+ * Métricas:
+ *   - Error recurrence rate:    ¿El mismo error ocurre dos veces?
+ *   - Stop rate:                ¿Cuántas veces el TDD gate paró el ciclo?
+ *   - First-try test pass rate: ¿Tests pasan en el primer intento?
+ *   - Rework index:             ¿Cuántos ciclos tocan los mismos archivos?
+ *   - Pattern velocity:         ¿Qué tan rápido suben patrones a HIGH?
+ *   - Memory growth:            ¿Cuánto conocimiento acumula por ciclo?
+ *
+ * Uso:
+ *   node effectiveness-report.cjs          → reporte completo
+ *   node effectiveness-report.cjs --json   → output JSON para dashboards
+ *   node effectiveness-report.cjs --short  → resumen de una línea por métrica
+ */
+
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+// ─── DB ───────────────────────────────────────────────────────────────────────
+
+function openDB(projectRoot) {
+  const dbPath = path.join(projectRoot, '.agentic/memoria.db');
+  try { return new (require('better-sqlite3'))(dbPath, { readonly: true }); } catch {}
+  try { const { DatabaseSync } = require('node:sqlite'); return new DatabaseSync(dbPath); } catch {}
+  return null;
+}
+
+// ─── CALCULAR MÉTRICAS POR VENTANA DE CICLOS ─────────────────────────────────
+
+function calcWindowMetrics(db, cycleIds) {
+  if (!cycleIds || cycleIds.length === 0) {
+    return { stops: 0, stop_rate: 0, errors_found: 0, errors_per_cycle: 0,
+             tests_total: 0, tests_passed: 0, first_try_rate: 0,
+             patterns_applied: 0, patterns_per_cycle: 0, cycles: 0 };
+  }
+
+  const placeholders = cycleIds.map(() => '?').join(',');
+  const safe = (fn) => { try { return fn(); } catch { return null; } };
+
+  const stops = safe(() =>
+    db.prepare(`SELECT COUNT(*) as n FROM ciclos WHERE estado='STOP' AND ciclo_id IN (${placeholders})`).get(...cycleIds)?.n
+  ) || 0;
+
+  const errorsFound = safe(() => {
+    const rows = db.prepare(`SELECT errores_encontrados FROM ciclos WHERE ciclo_id IN (${placeholders})`).all(...cycleIds);
+    return rows.reduce((s, r) => s + (parseInt(r.errores_encontrados) || 0), 0);
+  }) || 0;
+
+  // Tests: sumar de todos los ciclos
+  let testsTotal = 0, testsPassed = 0;
+  safe(() => {
+    const rows = db.prepare(`SELECT tests_corridos FROM ciclos WHERE ciclo_id IN (${placeholders})`).all(...cycleIds);
+    rows.forEach(r => {
+      try {
+        const t = JSON.parse(r.tests_corridos || '{}');
+        testsTotal  += (t.total  || parseInt(r.tests_corridos) || 0);
+        testsPassed += (t.passed || parseInt(r.tests_corridos) || 0);
+      } catch {
+        const n = parseInt(r.tests_corridos) || 0;
+        testsTotal += n; testsPassed += n;
+      }
+    });
+  });
+
+  // Patrones aplicados
+  const patternsApplied = safe(() => {
+    const rows = db.prepare(`SELECT patrones_aplicados FROM ciclos WHERE ciclo_id IN (${placeholders})`).all(...cycleIds);
+    return rows.reduce((s, r) => {
+      try { return s + JSON.parse(r.patrones_aplicados || '[]').length; }
+      catch { return s; }
+    }, 0);
+  }) || 0;
+
+  const n = cycleIds.length;
+  return {
+    cycles:              n,
+    stops,
+    stop_rate:           n > 0 ? Math.round((stops / n) * 100) : 0,
+    errors_found:        errorsFound,
+    errors_per_cycle:    n > 0 ? Math.round((errorsFound / n) * 10) / 10 : 0,
+    tests_total:         testsTotal,
+    tests_passed:        testsPassed,
+    first_try_rate:      testsTotal > 0 ? Math.round((testsPassed / testsTotal) * 100) : 100,
+    patterns_applied:    patternsApplied,
+    patterns_per_cycle:  n > 0 ? Math.round((patternsApplied / n) * 10) / 10 : 0,
+  };
+}
+
+// ─── ERROR RECURRENCE RATE ───────────────────────────────────────────────────
+
+function calcErrorRecurrence(db, allCycleIds, splitAt) {
+  const safe = (fn) => { try { return fn(); } catch { return 0; } };
+
+  // Errores únicos en primera mitad
+  const firstHalf   = allCycleIds.slice(0, splitAt);
+  const secondHalf  = allCycleIds.slice(splitAt);
+
+  if (firstHalf.length === 0 || secondHalf.length === 0) return { rate: 0, recurred: 0, total_first: 0 };
+
+  const ph1 = firstHalf.map(() => '?').join(',');
+  const ph2 = secondHalf.map(() => '?').join(',');
+
+  // Patrones de error en primera mitad
+  const firstErrors = safe(() =>
+    db.prepare(`SELECT titulo FROM nodos WHERE tipo='error' AND fecha_creacion IN (
+      SELECT fecha_inicio FROM ciclos WHERE ciclo_id IN (${ph1})
+    )`).all(...firstHalf).map(r => r.titulo)
+  ) || [];
+
+  // Mismos patrones vistos en segunda mitad
+  let recurred = 0;
+  if (firstErrors.length > 0 && secondHalf.length > 0) {
+    firstErrors.forEach(titulo => {
+      if (!titulo) return;
+      const found = safe(() =>
+        db.prepare(`SELECT COUNT(*) as n FROM nodos WHERE tipo='error' AND titulo=? AND fecha_creacion IN (
+          SELECT fecha_inicio FROM ciclos WHERE ciclo_id IN (${ph2})
+        )`).get(titulo, ...secondHalf)?.n
+      );
+      if (found > 0) recurred++;
+    });
+  }
+
+  return {
+    rate:        firstErrors.length > 0 ? Math.round((recurred / firstErrors.length) * 100) : 0,
+    recurred,
+    total_first: firstErrors.length,
+  };
+}
+
+// ─── PATTERN VELOCITY ────────────────────────────────────────────────────────
+
+function calcPatternVelocity(db) {
+  const safe = (fn) => { try { return fn(); } catch { return null; } };
+
+  const highNodes = safe(() =>
+    db.prepare(`SELECT aplicado, fecha_creacion, fecha_update FROM nodos
+      WHERE confianza='ALTA' AND estado='ACTIVO' AND tipo='patron'`).all()
+  ) || [];
+
+  if (highNodes.length === 0) return { avg_cycles_to_high: null, total_high: 0 };
+
+  // Promedio de aplicaciones para llegar a HIGH (proxy: campo aplicado)
+  const avgApplied = highNodes.reduce((s, n) => s + (n.aplicado || 0), 0) / highNodes.length;
+
+  return {
+    avg_cycles_to_high: Math.round(avgApplied * 10) / 10,
+    total_high:         highNodes.length,
+  };
+}
+
+// ─── REWORK INDEX ────────────────────────────────────────────────────────────
+
+function calcReworkIndex(db, cycleIds) {
+  if (!cycleIds || cycleIds.length < 2) return { index: 0, reworked_areas: 0 };
+
+  const safe = (fn) => { try { return fn(); } catch { return null; } };
+  const ph = cycleIds.map(() => '?').join(',');
+
+  // Áreas que aparecen en más de un ciclo = rework
+  const areas = safe(() =>
+    db.prepare(`SELECT n.area, COUNT(DISTINCT c.ciclo_id) as cycles
+      FROM nodos n
+      JOIN ciclos c ON n.fecha_creacion >= c.fecha_inicio AND n.fecha_creacion <= COALESCE(c.fecha_fin, datetime('now'))
+      WHERE c.ciclo_id IN (${ph})
+      GROUP BY n.area HAVING cycles > 1`).all(...cycleIds)
+  ) || [];
+
+  const totalAreas = safe(() =>
+    db.prepare(`SELECT COUNT(DISTINCT area) as n FROM nodos WHERE estado='ACTIVO'`).get()?.n
+  ) || 1;
+
+  return {
+    index:         areas.length,
+    reworked_areas:areas.length,
+    total_areas:   totalAreas,
+    rate:          Math.round((areas.length / totalAreas) * 100),
+  };
+}
+
+// ─── REPORTE COMPLETO ─────────────────────────────────────────────────────────
+
+function generateReport(projectRoot, options = {}) {
+  projectRoot = projectRoot || process.cwd();
+  const db = openDB(projectRoot);
+  if (!db) return { error: 'DB no disponible' };
+
+  const safe = (fn) => { try { return fn(); } catch { return null; } };
+
+  // Obtener todos los ciclos en orden cronológico
+  const allCycles = safe(() =>
+    db.prepare(`SELECT ciclo_id, descripcion, fecha_inicio, estado FROM ciclos ORDER BY fecha_inicio ASC`).all()
+  ) || [];
+
+  if (allCycles.length < 2) {
+    db.close();
+    return { error: `Solo ${allCycles.length} ciclo(s) — se necesitan al menos 2 para comparar`, cycles: allCycles.length };
+  }
+
+  const n         = allCycles.length;
+  const splitAt   = Math.max(1, Math.floor(n / 2));
+  const firstIds  = allCycles.slice(0, splitAt).map(c => c.ciclo_id);
+  const lastIds   = allCycles.slice(splitAt).map(c => c.ciclo_id);
+  const last3Ids  = allCycles.slice(-3).map(c => c.ciclo_id);
+  const first3Ids = allCycles.slice(0, 3).map(c => c.ciclo_id);
+
+  // Calcular métricas
+  const first  = calcWindowMetrics(db, firstIds);
+  const last   = calcWindowMetrics(db, lastIds);
+  const first3 = calcWindowMetrics(db, first3Ids);
+  const last3  = calcWindowMetrics(db, last3Ids);
+
+  const recurrence = calcErrorRecurrence(db, allCycles.map(c => c.ciclo_id), splitAt);
+  const velocity   = calcPatternVelocity(db);
+  const rework     = calcReworkIndex(db, last3Ids);
+
+  // Memoria evolution
+  const memFirst = safe(() =>
+    db.prepare(`SELECT COUNT(*) as n FROM nodos WHERE fecha_creacion <= (
+      SELECT fecha_inicio FROM ciclos ORDER BY fecha_inicio ASC LIMIT 1 OFFSET ?
+    )`).get(Math.max(0, splitAt - 1))?.n
+  ) || 0;
+  const memNow = safe(() =>
+    db.prepare(`SELECT COUNT(*) as n FROM nodos WHERE estado='ACTIVO'`).get()?.n
+  ) || 0;
+
+  // Delta helpers
+  const delta = (before, after) => {
+    if (before === 0 && after === 0) return { val: 0, pct: 0, dir: '→' };
+    if (before === 0) return { val: after, pct: 100, dir: '↑' };
+    const pct = Math.round(((after - before) / before) * 100);
+    return { val: after - before, pct: Math.abs(pct), dir: pct > 0 ? '↑' : pct < 0 ? '↓' : '→' };
+  };
+
+  const report = {
+    generated: new Date().toISOString(),
+    project:   path.basename(projectRoot),
+    total_cycles: n,
+    window: {
+      first_half:  { cycles: firstIds.length,  label: `ciclos 1-${firstIds.length}` },
+      second_half: { cycles: lastIds.length,   label: `ciclos ${firstIds.length + 1}-${n}` },
+    },
+
+    metrics: {
+      stop_rate: {
+        label:       'Stop rate (TDD gate)',
+        description: 'Ciclos donde el harness tuvo que parar',
+        first:       `${first.stop_rate}%`,
+        last:        `${last.stop_rate}%`,
+        delta:       delta(first.stop_rate, last.stop_rate),
+        trend:       last.stop_rate < first.stop_rate ? 'improving' : last.stop_rate > first.stop_rate ? 'degrading' : 'stable',
+        raw:         { first: first.stop_rate, last: last.stop_rate },
+      },
+      errors_per_cycle: {
+        label:       'Errores por ciclo',
+        description: 'Promedio de errores nuevos encontrados por ciclo',
+        first:       first.errors_per_cycle,
+        last:        last.errors_per_cycle,
+        delta:       delta(first.errors_per_cycle, last.errors_per_cycle),
+        trend:       last.errors_per_cycle < first.errors_per_cycle ? 'improving' : 'stable',
+        raw:         { first: first.errors_per_cycle, last: last.errors_per_cycle },
+      },
+      first_try_rate: {
+        label:       'Tests en primer intento',
+        description: '% de tests que pasan sin self-healing',
+        first:       `${first.first_try_rate}%`,
+        last:        `${last.first_try_rate}%`,
+        delta:       delta(first.first_try_rate, last.first_try_rate),
+        trend:       last.first_try_rate >= first.first_try_rate ? 'improving' : 'degrading',
+        raw:         { first: first.first_try_rate, last: last.first_try_rate },
+      },
+      error_recurrence: {
+        label:       'Recurrencia de errores',
+        description: '% de errores de la primera mitad que volvieron a ocurrir',
+        value:       `${recurrence.rate}%`,
+        recurred:    recurrence.recurred,
+        total:       recurrence.total_first,
+        trend:       recurrence.rate < 20 ? 'good' : recurrence.rate < 50 ? 'moderate' : 'needs_work',
+      },
+      pattern_velocity: {
+        label:       'Velocidad de patrones',
+        description: 'Promedio de aplicaciones para llegar a HIGH confidence',
+        avg_to_high: velocity.avg_cycles_to_high,
+        total_high:  velocity.total_high,
+        trend:       velocity.total_high > 5 ? 'good' : 'building',
+      },
+      memory_growth: {
+        label:       'Crecimiento de memoria',
+        description: 'Nodos de conocimiento acumulados',
+        at_start:    memFirst,
+        now:         memNow,
+        delta:       memNow - memFirst,
+        per_cycle:   n > 0 ? Math.round(((memNow - memFirst) / n) * 10) / 10 : 0,
+        trend:       memNow > memFirst ? 'growing' : 'stable',
+      },
+      patterns_per_cycle: {
+        label:       'Patrones aplicados por ciclo',
+        description: 'Cuántos patrones de memoria usa el agente en cada ciclo',
+        first:       first.patterns_per_cycle,
+        last:        last.patterns_per_cycle,
+        delta:       delta(first.patterns_per_cycle, last.patterns_per_cycle),
+        trend:       last.patterns_per_cycle >= first.patterns_per_cycle ? 'improving' : 'stable',
+        raw:         { first: first.patterns_per_cycle, last: last.patterns_per_cycle },
+      },
+    },
+
+    summary: {
+      improving: [],
+      stable:    [],
+      needs_work:[],
+    },
+  };
+
+  // Clasificar métricas en el summary
+  Object.entries(report.metrics).forEach(([key, m]) => {
+    if (!m.trend) return;
+    if (['improving','good','growing'].includes(m.trend)) report.summary.improving.push(m.label);
+    else if (['degrading','needs_work'].includes(m.trend)) report.summary.needs_work.push(m.label);
+    else report.summary.stable.push(m.label);
+  });
+
+  db.close();
+  return report;
+}
+
+// ─── PRINT REPORT ─────────────────────────────────────────────────────────────
+
+function printReport(report) {
+  if (report.error) {
+    console.log(`\n[REPORT] ${report.error}\n`);
+    return;
+  }
+
+  const arrow = (trend) => trend === 'improving' || trend === 'good' || trend === 'growing' ? '✅' :
+                            trend === 'degrading' || trend === 'needs_work' ? '⚠️' : '→';
+
+  console.log('\n' + '═'.repeat(60));
+  console.log('  Agentic KDD — Effectiveness Report');
+  console.log(`  ${report.project} · ${report.total_cycles} ciclos totales`);
+  console.log('═'.repeat(60));
+  console.log(`\n  Comparando: ${report.window.first_half.label} vs ${report.window.second_half.label}\n`);
+
+  const m = report.metrics;
+
+  console.log('  ① Stop rate (TDD gate paró el ciclo)');
+  console.log(`     Antes: ${m.stop_rate.first}  →  Ahora: ${m.stop_rate.last}  ${arrow(m.stop_rate.trend)}`);
+  if (m.stop_rate.delta.pct > 0) console.log(`     ${m.stop_rate.delta.dir} ${m.stop_rate.delta.pct}% ${m.stop_rate.trend}`);
+
+  console.log('\n  ② Errores por ciclo');
+  console.log(`     Antes: ${m.errors_per_cycle.first}  →  Ahora: ${m.errors_per_cycle.last}  ${arrow(m.errors_per_cycle.trend)}`);
+
+  console.log('\n  ③ Tests pasan en primer intento');
+  console.log(`     Antes: ${m.first_try_rate.first}  →  Ahora: ${m.first_try_rate.last}  ${arrow(m.first_try_rate.trend)}`);
+
+  console.log('\n  ④ Recurrencia de errores');
+  console.log(`     ${m.error_recurrence.recurred}/${m.error_recurrence.total} errores volvieron a ocurrir = ${m.error_recurrence.value}  ${arrow(m.error_recurrence.trend)}`);
+
+  console.log('\n  ⑤ Memoria acumulada');
+  console.log(`     Inicio: ${m.memory_growth.at_start} nodos  →  Ahora: ${m.memory_growth.now} nodos  (+${m.memory_growth.delta})`);
+  console.log(`     ${m.memory_growth.per_cycle} nodos nuevos por ciclo promedio`);
+
+  console.log('\n  ⑥ Patrones de memoria aplicados por ciclo');
+  console.log(`     Antes: ${m.patterns_per_cycle.first}  →  Ahora: ${m.patterns_per_cycle.last}  ${arrow(m.patterns_per_cycle.trend)}`);
+
+  console.log('\n  ⑦ Patrones con confianza HIGH');
+  console.log(`     ${m.pattern_velocity.total_high} patrones promovidos a HIGH`);
+  if (m.pattern_velocity.avg_to_high) console.log(`     Promedio de ${m.pattern_velocity.avg_to_high} aplicaciones para llegar a HIGH`);
+
+  if (report.summary.improving.length > 0) {
+    console.log(`\n  ✅ Mejorando:   ${report.summary.improving.join(' · ')}`);
+  }
+  if (report.summary.needs_work.length > 0) {
+    console.log(`  ⚠️  Atención:    ${report.summary.needs_work.join(' · ')}`);
+  }
+
+  console.log('\n' + '═'.repeat(60));
+  console.log('  Generado:', new Date(report.generated).toLocaleString('es-ES'));
+  console.log('═'.repeat(60) + '\n');
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const projectRoot = process.cwd();
+  const report = generateReport(projectRoot);
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printReport(report);
+  }
+}
+
+module.exports = { generateReport, printReport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-kdd",
-  "version": "3.2.2",
+  "version": "3.3.1",
   "description": "Autonomous development pipeline — aa: · ag: · audit: · AST graph · Harness · Specs · Impact analysis · Decision trail · Metrics · MCP server. Works with Cursor and Claude Code.",
   "main": "src/index.js",
   "bin": {