agentic-kdd 3.3.1 → 3.5.1

package/CLAUDE.md

@@ -0,0 +1,375 @@
+# ============================================================
+# AGENTIC KDD v2 — CONTROL TOTAL
+# ============================================================
+# Este archivo reemplaza cualquier CLAUDE.md previo.
+# Si tenías instrucciones propias, pégalas al final
+# en la sección "INSTRUCCIONES DEL PROYECTO".
+# ============================================================
+
+## PRIORIDAD ABSOLUTA
+
+`aa:` y `audit:` anulan TODO lo demás.
+No importa qué otros archivos de contexto existan en el proyecto.
+No importa qué instrucciones previas había en este CLAUDE.md.
+Cuando aparecen esos comandos — solo existe Agentic KDD.
+
+## CUANDO VES aa: sprint
+
+Lee `.agentic/agentes/09-sprint.md` y ejecuta su protocolo completo.
+Coordina múltiples tareas encadenadas donde el output de cada una alimenta la siguiente.
+La memoria KDD fluye entre todas las tareas del sprint.
+
+Variantes:
+- `aa: sprint — [objetivo]` con lista de tareas explícitas
+- `aa: sprint — [objetivo]` sin lista → inferir tareas y proponer antes de ejecutar
+- `aa: sprint skip` → saltar tarea actual y continuar
+- `aa: sprint abort` → cancelar sprint, mantener lo completado
+
+---
+
+## CUANDO VES aa: aprende
+
+Lee `.agentic/agentes/08-aprende.md` y ejecuta su protocolo completo.
+Analiza el código del proyecto, detecta patrones/errores/decisiones implícitas
+y propone qué registrar en memoria KDD — siempre pregunta antes de escribir.
+
+Variantes: `aa: aprende`, `aa: aprende — módulo [x]`, `aa: aprende [archivo]`,
+`aa: aprende — error: [x]`, `aa: aprende — decisión: [x]`, `aa: aprende — patrón: [x]`
+
+---
+
+## CUANDO VES aa: sprint
+
+Lee `.agentic/agentes/09-sprint.md` y ejecuta su protocolo completo.
+Coordina múltiples tareas encadenadas donde el output de cada una alimenta la siguiente.
+La memoria KDD fluye entre todas las tareas del sprint.
+
+Variantes:
+- `aa: sprint — [objetivo]` con lista de tareas explícitas
+- `aa: sprint — [objetivo]` sin lista → inferir tareas y proponer antes de ejecutar
+- `aa: sprint skip` → saltar tarea actual y continuar
+- `aa: sprint abort` → cancelar sprint, mantener lo completado
+
+---
+
+## CUANDO VES aa: aprende
+
+Lee `.agentic/agentes/08-aprende.md` y ejecuta su protocolo completo.
+Analiza el proyecto, detecta patrones/errores/decisiones implícitas
+y propone que registrar — siempre pregunta antes de escribir.
+
+Variantes: aa: aprende / aa: aprende modulo [x] / aa: aprende [archivo]
+aa: aprende error: [x] / aa: aprende decision: [x] / aa: aprende patron: [x]
+
+---
+
+## CUANDO VES aa: help
+
+Mostrar exactamente esto:
+
+```
+╔══════════════════════════════════════════════════╗
+║  AGENTIC KDD v2 — Comandos disponibles          ║
+╚══════════════════════════════════════════════════╝
+
+Pipeline de desarrollo:
+  aa: configurar          → configuración inicial del proyecto
+  aa: [tu tarea]          → pipeline completo autónomo
+  aa: continúa — [resp]   → retomar después de un STOP
+  aa: aprende             → absorber conocimiento de trabajo hecho fuera del pipeline
+  aa: help                → muestra este menú
+
+Departamento QA:
+  audit: help             → muestra comandos de auditoría
+  audit: auditar          → auditoría completa
+  audit: [área]           → auditoría específica
+
+Consulta del grafo (en terminal):
+  akdd graph              → estado del grafo de conocimiento
+  akdd update             → actualizar Agentic KDD
+```
+
+## CUANDO VES aa: sprint
+
+Lee `.agentic/agentes/09-sprint.md` y ejecuta su protocolo completo.
+Coordina múltiples tareas encadenadas donde el output de cada una alimenta la siguiente.
+La memoria KDD fluye entre todas las tareas del sprint.
+
+Variantes:
+- `aa: sprint — [objetivo]` con lista de tareas explícitas
+- `aa: sprint — [objetivo]` sin lista → inferir tareas y proponer antes de ejecutar
+- `aa: sprint skip` → saltar tarea actual y continuar
+- `aa: sprint abort` → cancelar sprint, mantener lo completado
+
+---
+
+## CUANDO VES aa: aprende
+
+Lee `.agentic/agentes/08-aprende.md` y ejecuta su protocolo.
+Analiza el código, detecta patrones/errores/decisiones implícitas
+y propone qué registrar en memoria KDD antes de escribir nada.
+
+Variantes:
+- `aa: aprende` → analiza todo
+- `aa: aprende — módulo [x]` → foco en módulo
+- `aa: aprende [archivo]` → foco en archivo
+- `aa: aprende — error: [x]` → registrar error directo
+- `aa: aprende — decisión: [x]` → registrar decisión directo
+- `aa: aprende — patrón: [x]` → registrar patrón directo
+
+---
+
+## CUANDO VES aa:
+
+```
+1. Leer .agentic/config.md
+2. Leer .agentic/memoria/trabajo.md
+3. Si CONFIGURADO: NO → Setup primero
+4. Ejecutar pipeline completo sin pausar entre agentes
+5. No pedir confirmación al usuario entre fases
+6. Detener SOLO ante STOP genuino
+```
+
+Flujo completo:
+Orquestador → Analista → Front/Back → QA → Memoria
+
+## CUANDO VES audit:
+
+```
+1. Leer .audit/AUDIT.md
+2. Activar Director + subagentes indicados
+3. Generar reporte en _output/audit-[fecha].md
+4. NO tocar código — solo auditar
+```
+
+
+## CUANDO VES akdd <comando>
+
+Si el usuario escribe `akdd <comando>` en el chat, llamar el MCP tool correspondiente.
+El usuario NO necesita abrir terminal — funciona igual desde aquí.
+
+| Usuario escribe | MCP tool a llamar |
+|---|---|
+| `akdd health` | `system_health` |
+| `akdd health --fix` | `system_health` con `{fix: true}` |
+| `akdd update` | `update_project` |
+| `akdd collab init` | `collab_init` |
+| `akdd collab invite` | `collab_invite` |
+| `akdd collab status` | `collab_status` |
+| `akdd metrics` | `metrics_summary` |
+| `akdd benchmarks` | `report_benchmarks` |
+| `akdd trail` | `recent_ciclos` |
+| `akdd cure` | `mem_curate` |
+| `akdd cure report` | `mem_curate` con `{mode: "report"}` |
+| `akdd llms` | `generate_llms_txt` |
+| `akdd ast` | `ast_index` |
+| `akdd ast-impact <f>` | `ast_impact` con `{target: "<f>"}` |
+| `akdd why <f>` | `decision_why` con `{target: "<f>"}` |
+| `akdd audit` | `memory_audit` |
+| `akdd causal-prune` | `causal_prune` |
+
+Los comandos que SÍ requieren terminal (solo estos dos):
+- `npm install -g agentic-kdd` → instalar el CLI por primera vez
+- `akdd init` → primera instalación en un proyecto nuevo
+
+Todo lo demás corre desde el chat.
+
+## SIN aa: O audit:
+
+Responder normalmente usando el contexto del proyecto.
+
+## ARCHIVOS CLAVE
+
+- `.agentic/config.md`     → cerebro del proyecto
+- `.agentic/PLAN.md`       → tarea activa
+- `.agentic/memoria/`      → memoria KDD persistente
+- `.agentic/agentes/`      → instrucciones de cada agente
+- `.agentic/conocimiento/` → docs del proyecto
+- `.audit/`                → Departamento QA
+
+
+
+## RECUPERACIÓN DE SESIÓN
+
+Si el usuario pega un bloque que empieza con `# Checkpoint Agentic KDD`:
+1. Leer el checkpoint completo
+2. Cargar el contexto de la última tarea y las anteriores
+3. Responder: "✅ Contexto recuperado — continuando desde: [última tarea]"
+4. Estar listo para ejecutar la siguiente instrucción con ese contexto
+
+Si el usuario escribe `akdd historial`:
+→ Llamar MCP tool `session_historial`
+→ Mostrar el resultado formateado
+
+
+## DRY-RUN MODE — aa: --dry-run
+
+Si el usuario escribe `aa: --dry-run <tarea>`:
+
+1. Correr Orquestador → Analista → Dev (SOLO planificación)
+2. El Dev describe los cambios que HARÍA sin ejecutarlos:
+   - Lista de archivos que modificaría
+   - Diff propuesto por archivo (pseudocódigo o diff real si es posible)
+   - Contratos que verificaría
+   - Blast radius estimado
+3. Presentar como:
+   ```
+   📋 DRY-RUN: [tarea]
+   
+   Archivos que modificaría:
+     - src/auth.ts (líneas 45-67: cambio de lógica de refresh token)
+     - src/session.ts (línea 12: actualizar TTL)
+   
+   Contratos en riesgo: AUTH-001 (PROTECTED), AUTH-004 (VERIFIED)
+   Blast radius: HIGH (8 contratos)
+   
+   ¿Proceder con implementación real? (aa: implement [tarea])
+   ```
+4. NO escribir ningún archivo. NO correr tests. NO modificar memoria.
+5. El dev decide si proceder con `aa: implement <tarea>`
+
+
+## DENY LIST — Operaciones que requieren confirmación explícita
+
+NUNCA ejecutar estas operaciones sin confirmación explícita en el chat:
+
+```
+REQUIEREN CONFIRMACIÓN EXPLÍCITA DEL DEV:
+  - rm -rf / rmdir /s  → eliminar directorios completos
+  - DROP TABLE / DROP DATABASE → operaciones SQL destructivas
+  - DELETE FROM [tabla] sin WHERE → borrado masivo
+  - git push --force → force push a ramas protegidas
+  - npm publish → publicar paquetes npm
+  - docker rm / docker rmi → eliminar contenedores/imágenes
+  - Modificar .env, .env.production, secrets.* → archivos de secretos
+  - Migraciones SQL irreversibles → ALTER TABLE DROP COLUMN
+  - Deploy a producción → cualquier comando que afecte prod
+```
+
+Si el pipeline genera una de estas operaciones:
+1. STOP el pipeline
+2. Mostrar exactamente qué operación intentaría correr
+3. Preguntar confirmación explícita: "¿Confirmas ejecutar: [comando]?"
+4. Solo proceder si el dev responde SÍ explícitamente
+
+
+## ENCADENAMIENTO DE COMANDOS
+
+Si el mensaje tiene esta forma:
+```
+aa: <tarea> audit: <tipo>
+```
+O cualquier combinación de `aa:` seguido de `audit:`, `ag:` u otro comando al final:
+
+1. Ejecuta el pipeline `aa:` completo para la tarea
+2. Al terminar, ejecuta automáticamente el comando encadenado
+3. Reporta ambos resultados juntos al final
+
+Ejemplos válidos:
+```
+aa: implementa el módulo de pagos audit: frontend
+aa: refactoriza auth.ts audit: seguridad
+aa: agrega las invitaciones ag: review src/routes/invitations.ts
+```
+
+El encadenamiento solo aplica cuando el segundo comando está AL FINAL del mensaje,
+separado por espacio. No interrumpir el pipeline principal para ejecutarlo antes.
+
+
+## QA MEJORADO — VALIDACIÓN CONTRA HISTORIAL
+
+En la fase QA de cada ciclo `aa:`, además de verificar los criterios de aceptación
+de la tarea actual, verificar lo siguiente contra la memoria del proyecto:
+
+1. **Spec compliance** — ¿El comportamiento nuevo contradice alguna decisión
+   documentada en memoria con confianza HIGH o MEDIA?
+   Si sí → STOP con reporte exacto de la contradicción.
+
+2. **Error pattern check** — ¿Alguno de los cambios toca un área donde hay
+   errores HIGH confidence en memoria?
+   Si sí → ejecutar los tests específicos de esa área antes de declarar PASS.
+
+3. **Contract preservation** — El Preservation Gate ya cubre esto, pero en QA
+   también verificar que los contratos VERIFIED del módulo afectado siguen verdes.
+
+4. **Behavioral consistency** — Si hay specs en `.agentic/specs/` para el módulo
+   tocado, verificar que el comportamiento nuevo es consistente con el spec.
+
+Si alguno de estos checks falla → QA FAIL con razón específica, no solo
+"tests failing". El dev necesita saber exactamente qué spec, qué error histórico
+o qué contrato se está violando.
+
+
+## DETECCIÓN Y CORRECCIÓN AUTÓNOMA DE PATRONES
+
+Cuando durante un ciclo `aa:` encuentres el mismo patrón de error/bug en otros
+módulos del proyecto, aplica esta lógica automáticamente:
+
+### Paso 1 — Prerequisite check
+Antes de aplicar los hallazgos, verificar si alguno bloquea la validación
+del fix principal:
+- ¿Algún módulo con el patrón es una dependencia del fix actual?
+- Si SÍ → corrígelo PRIMERO, luego el fix pedido
+
+### Paso 2 — Clasificar por riesgo (tabla de criticidad)
+Para cada hallazgo, determinar el nivel de riesgo del archivo:
+
+| Nivel     | Acción autónoma                                    |
+|-----------|---------------------------------------------------|
+| CRITICAL  | NUNCA tocar solo — siempre avisar primero          |
+| SENSITIVE | Solo tocar si hay contrato verificado que respalde |
+| NORMAL    | Actuar solo si el patrón ya está en memoria        |
+| FREE      | Actuar siempre autónomamente                       |
+
+### Paso 3 — Aplicar
+- Archivos AUTO_FIX → corregir en el mismo ciclo sin preguntar
+- Archivos WARN → incluir en el reporte final como pendientes
+
+### Paso 4 — Reporte al final del ciclo
+Al terminar, incluir en el reporte:
+```
+✅ Tarea completada: [descripción]
+
+🔍 Patrones detectados y corregidos autónomamente:
+   - [módulo]: [qué se corrigió] (riesgo: NORMAL, historial: 3x)
+   
+⚠️  Patrones detectados — requieren confirmación:
+   - [módulo]: [qué encontré] (riesgo: CRITICAL — revisar manualmente)
+```
+
+NO preguntar en medio del ciclo. NO interrumpir. Actuar y reportar al final.
+
+## DETECCIÓN AUTOMÁTICA DE TAREAS SIN aa:
+
+Esta regla actúa como red de seguridad para cuando el dev olvida escribir `aa:`.
+
+Si el mensaje NO tiene `aa:` pero cumple los criterios de abajo,
+trátalo exactamente como si tuviera `aa:` — ejecuta el pipeline completo.
+
+### TRATAR COMO aa: si el mensaje:
+- Empieza con verbo de acción técnica:
+  "implementa", "crea", "crea un", "fix", "arregla", "agrega", "añade",
+  "modifica", "refactoriza", "conecta", "integra", "genera", "construye",
+  "desarrolla", "corrige", "actualiza", "migra", "convierte", "extrae",
+  "aplica", "añade soporte", "haz que", "necesito que"
+- Menciona un archivo o módulo específico: "en auth.ts", "en el módulo de pagos", "en src/"
+- Tiene contexto técnico claro con intención de cambio: "el bug de X", "la feature de Y", "el error en Z"
+- Empieza con prefijo técnico: `fix:` / `feat:` / `build:` / `dev:` / `chore:`
+
+### NO ejecutar el pipeline si:
+- Es una pregunta (termina en `?`)
+- Empieza con: "explícame", "qué es", "cómo funciona", "cuándo", "por qué", "dónde", "muéstrame", "dame", "qué piensas"
+- Es una consulta de estado: `akdd buscar`, `akdd health`, `akdd metrics`, `akdd trail`
+- Es una conversación sobre el proyecto, no una acción sobre él
+
+### Comportamiento al detectar tarea sin aa:
+Antes de ejecutar, mostrar exactamente:
+```
+🔄 Detecté una tarea de desarrollo — ejecutando como aa:
+```
+Luego proceder con el pipeline completo como si el dev hubiera escrito `aa:`.
+
+
+# ============================================================
+# INSTRUCCIONES DEL PROYECTO — agregar las tuyas aquí abajo
+# ============================================================

package/autonomous-decision.cjs

@@ -53,6 +53,186 @@ const BLAST_LEVELS = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
 
 const DEFERRED_QUEUE_PATH = '.agentic/deferred_queue.json';
 
+// ─── FILE RISK TABLE ──────────────────────────────────────────────────────────
+
+const DEFAULT_RISK_TABLE = {
+  CRITICAL:  ['auth.ts', 'middleware/', '.env', 'prisma/schema', 'secrets'],
+  SENSITIVE: ['routes/auth', 'lib/prisma', 'collab-manager', 'harness'],
+  NORMAL:    ['routes/', 'lib/', 'services/', 'controllers/'],
+  FREE:      ['tests/', '__tests__/', 'utils/', 'validators', 'constants'],
+};
+
+function classifyFileRisk(filePath, projectRoot) {
+  let riskTable = DEFAULT_RISK_TABLE;
+  try {
+    const configPath = path.join(projectRoot || process.cwd(), '.agentic/config.md');
+    const config = fs.readFileSync(configPath, 'utf8');
+    const tableMatch = config.match(/\[file_risk_table\]([\s\S]*?)(?=\[|$)/);
+    if (tableMatch) {
+      const lines = tableMatch[1].trim().split(/\r?\n/).filter(Boolean);
+      const custom = { CRITICAL: [], SENSITIVE: [], NORMAL: [], FREE: [] };
+      lines.forEach(function(line) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx < 0) return;
+        const lvl = line.substring(0, colonIdx).trim().toUpperCase();
+        const vals = line.substring(colonIdx + 1).split(',').map(function(p) { return p.trim(); }).filter(Boolean);
+        if (custom[lvl]) custom[lvl].push.apply(custom[lvl], vals);
+      });
+      riskTable = {
+        CRITICAL:  DEFAULT_RISK_TABLE.CRITICAL.concat(custom.CRITICAL),
+        SENSITIVE: DEFAULT_RISK_TABLE.SENSITIVE.concat(custom.SENSITIVE),
+        NORMAL:    DEFAULT_RISK_TABLE.NORMAL.concat(custom.NORMAL),
+        FREE:      DEFAULT_RISK_TABLE.FREE.concat(custom.FREE),
+      };
+    }
+  } catch(e) {}
+
+  const fp = (filePath || '').replace(/\\/g, '/').toLowerCase();
+  for (var i = 0; i < riskTable.CRITICAL.length;  i++) if (fp.includes(riskTable.CRITICAL[i].toLowerCase()))  return 'CRITICAL';
+  for (var i = 0; i < riskTable.SENSITIVE.length; i++) if (fp.includes(riskTable.SENSITIVE[i].toLowerCase())) return 'SENSITIVE';
+  for (var i = 0; i < riskTable.FREE.length;      i++) if (fp.includes(riskTable.FREE[i].toLowerCase()))      return 'FREE';
+  for (var i = 0; i < riskTable.NORMAL.length;    i++) if (fp.includes(riskTable.NORMAL[i].toLowerCase()))    return 'NORMAL';
+  return 'NORMAL';
+}
+
+// ─── PATTERN DETECTION ACROSS MODULES ────────────────────────────────────────
+
+function detectPatternAcrossModules(db, errorSignatures, currentFiles, projectRoot) {
+  if (!db || !errorSignatures || errorSignatures.length === 0) return [];
+
+  const findings = [];
+  const currentAreas = (currentFiles || []).map(function(f) {
+    return path.basename(f, path.extname(f)).toLowerCase();
+  });
+
+  const sfn = function(fn) { try { return fn(); } catch(e) { return []; } };
+
+  errorSignatures.forEach(function(sig) {
+    if (!sig || sig.length < 3) return;
+
+    const likeQuery = '%' + sig + '%';
+    const placeholders = currentAreas.length > 0
+      ? 'AND area NOT IN (' + currentAreas.map(function() { return '?'; }).join(',') + ')'
+      : '';
+
+    let otherModules = [];
+    try {
+      otherModules = db.prepare(
+        'SELECT DISTINCT area, id, titulo, confianza, aplicado FROM nodos ' +
+        'WHERE tipo IN (\'error\', \'patron\') ' +
+        'AND (titulo LIKE ? OR contenido LIKE ?) ' +
+        'AND estado = \'ACTIVO\' ' +
+        placeholders + ' ORDER BY aplicado DESC LIMIT 8'
+      ).all.apply(null, [likeQuery, likeQuery].concat(currentAreas));
+    } catch(e) {}
+
+    otherModules.forEach(function(mod) {
+      const hasHistory = (mod.aplicado || 0) > 0;
+      const riskLevel  = classifyFileRisk(mod.area, projectRoot);
+
+      let knownFix = null;
+      try {
+        const fixRow = db.prepare(
+          'SELECT descripcion FROM relaciones_semanticas ' +
+          'WHERE desde_entidad LIKE ? AND tipo = \'was_fixed_by\' ' +
+          'AND (invalid_at IS NULL OR invalid_at = \'\') LIMIT 1'
+        ).get('%' + mod.area + '%');
+        if (fixRow) knownFix = fixRow.descripcion;
+      } catch(e) {}
+
+      let action;
+      if (riskLevel === 'CRITICAL') {
+        action = 'WARN';
+      } else if (riskLevel === 'SENSITIVE' && !knownFix) {
+        action = 'WARN';
+      } else if (hasHistory || knownFix) {
+        action = 'AUTO_FIX';
+      } else {
+        action = riskLevel === 'FREE' ? 'AUTO_FIX' : 'WARN';
+      }
+
+      findings.push({
+        module:      mod.area,
+        signature:   sig,
+        titulo:      mod.titulo,
+        risk_level:  riskLevel,
+        has_history: hasHistory,
+        known_fix:   knownFix,
+        action:      action,
+        reason: action === 'AUTO_FIX'
+          ? 'Pattern in ' + mod.area + ' (' + (mod.aplicado || 0) + 'x) — auto-fixing'
+          : riskLevel + ' file — requires confirmation before touching ' + mod.area,
+      });
+    });
+  });
+
+  const seen = {};
+  return findings.filter(function(f) {
+    const key = f.module + ':' + f.signature;
+    if (seen[key]) return false;
+    seen[key] = true;
+    return true;
+  });
+}
+
+// ─── PREREQUISITE CHECK FOR FINDINGS ─────────────────────────────────────────
+
+function prerequisiteCheckFindings(db, findings, currentFiles) {
+  if (!db || !findings || !findings.length) {
+    return { prerequisites: [], non_blockers: findings || [], can_proceed: true, fix_order: [{ step: 'MAIN_TASK' }] };
+  }
+
+  const prerequisites = [];
+  const nonBlockers   = [];
+
+  findings.forEach(function(finding) {
+    var isPrerequisite = false;
+
+    try {
+      (currentFiles || []).forEach(function(file) {
+        const bn   = path.basename(file);
+        const deps = db.prepare(
+          'SELECT hacia_entidad FROM relaciones_semanticas ' +
+          'WHERE desde_entidad LIKE ? ' +
+          'AND tipo IN (\'depende_de\', \'importa\', \'usa\', \'llama\') ' +
+          'AND (invalid_at IS NULL OR invalid_at = \'\') LIMIT 10'
+        ).all('%' + bn + '%').map(function(r) { return r.hacia_entidad; });
+
+        if (deps.some(function(d) {
+          return d && d.toLowerCase().includes(finding.module.toLowerCase());
+        })) {
+          isPrerequisite = true;
+        }
+      });
+    } catch(e) {}
+
+    if (isPrerequisite) {
+      prerequisites.push(Object.assign({}, finding, {
+        prerequisite_reason: finding.module + ' is upstream of current task — fix first',
+      }));
+    } else {
+      nonBlockers.push(finding);
+    }
+  });
+
+  const autoFixable = nonBlockers.filter(function(f) { return f.action === 'AUTO_FIX'; });
+  const warnOnly    = prerequisites.concat(nonBlockers.filter(function(f) { return f.action === 'WARN'; }));
+
+  const fixOrder = prerequisites.map(function(p) { return Object.assign({}, p, { when: 'BEFORE_MAIN_TASK' }); });
+  fixOrder.push({ step: 'MAIN_TASK' });
+  autoFixable.forEach(function(n) { fixOrder.push(Object.assign({}, n, { when: 'AFTER_MAIN_TASK' })); });
+
+  return {
+    prerequisites: prerequisites,
+    non_blockers:  nonBlockers,
+    can_proceed:   prerequisites.length === 0,
+    auto_fixable:  autoFixable,
+    warn_only:     warnOnly,
+    fix_order:     fixOrder,
+  };
+}
+
+
 // ─── DB ───────────────────────────────────────────────────────────────────────
 
 function openDB(projectRoot) {

package/bin/akdd.js

@@ -66,6 +66,15 @@ const HELP = `
     akdd creative apply <id>   Apply a suggestion
     akdd creative wins         View applied creative improvements
 
+  Memory (ranked retrieval):
+    akdd recall "query"    Ranked BM25+vector search — replaces full file reads
+    akdd memory stats      Memory retrieval stats (indexed, coverage, mode)
+    akdd memory index      Re-index all .agentic/memoria/*.md files
+    akdd validate scan     Scan all memory for stale/obsolete/poisoned entries
+    akdd validate report   Health report of knowledge base
+    akdd telemetry         Telemetry summary (spans, STOPs, recalls)
+    akdd telemetry view    View last cycle trace (L4 audit trail)
+
   Autonomous decisions (L4):
     akdd decide <file>     Analyze a change — STOP/WARN/IMPLEMENT/DEFER decision
     akdd deferred          View deferred queue (end-of-cycle suggestions)
@@ -276,6 +285,28 @@ switch (command) {
     break;
   }
 
+  // ── v3.4: KDD Memory, Knowledge Validator, Telemetry ─────────────────────
+  case 'recall':
+    runModule('kdd-memory.cjs', 'recall', args.slice(1).join(' '));
+    break;
+  case 'memory':
+    const sub = arg1 || 'stats';
+    if (sub === 'index')  runModule('kdd-memory.cjs', 'index');
+    else if (sub === 'sync') runModule('kdd-memory.cjs', 'sync');
+    else runModule('kdd-memory.cjs', 'stats');
+    break;
+  case 'validate':
+    const vsub = arg1 || 'report';
+    if (vsub === 'scan')       runModule('knowledge-validator.cjs', 'scan');
+    else if (vsub === 'report') runModule('knowledge-validator.cjs', 'report');
+    else runModule('knowledge-validator.cjs', 'validate', arg1);
+    break;
+  case 'telemetry':
+    const tsub = arg1 || 'summary';
+    if (tsub === 'view')    runModule('telemetry.cjs', 'view', arg2 || '');
+    else runModule('telemetry.cjs', 'summary');
+    break;
+
   // ── v3.3: Autonomous Decision Engine ──────────────────────────────────────
   case 'decide': {
     const files = args.slice(1);