agentic-kdd 3.5.5 → 3.5.7

package/README.md

@@ -1,68 +1,153 @@
-# agentic-kdd CLI
+# Agentic KDD v3.6
 
-Install [Agentic KDD](https://github.com/Adrianlpz211/Agentic-KDD) in any project with one command.
+> Autonomous development pipeline with persistent knowledge memory. Forces TDD, blocks spec violations before build, and eliminates repeated errors across sessions.
 
-## Install
+[![npm](https://img.shields.io/npm/v/agentic-kdd)](https://www.npmjs.com/package/agentic-kdd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## What it is
+
+Agentic KDD is a framework that runs inside **Cursor** and **Claude Code**. It turns your AI assistant into a disciplined development pipeline with:
+
+- **KDD Memory** — errors, patterns and decisions persist across sessions. The agent reads them before every task.
+- **TDD Gate** — deterministic self-healing loop. Forces tests to pass before continuing. Not a suggestion — it's code.
+- **Spec Gate** — blocks changes that contradict documented business rules before writing a single line.
+- **Security Gate** — detects JWT bypass, cross-tenant access and debug flags before build.
+- **Regression Guard** — protects healthy behaviors across cascading file changes.
+- **Contract Guard** — tracks passing test patterns and escalates them to protected contracts over time.
+
+---
+
+## Benchmark results (19 phases, Node.js + Python stacks)
+
+| Metric | Without | With | Change |
+|---|---|---|---|
+| Errors per phase | 2.6 | 0.0 | ✅ 100% |
+| Repeated errors | 3 | 0 | ✅ 100% |
+| Tests passing first try | 79% | 100% | ✅ +27pp |
+| Spec drift detections | 3 | 6 | ✅ +100% |
+| Cascade files correct | 4 | 11 | ✅ +175% |
+| Security issues detected | 1 | 2 | ✅ +100% |
+| Autonomous fixes | 4 | 7 | ✅ +75% |
+
+> N=1 project per benchmark. Treat as directional, not definitive. Reproducible benchmark repo in progress.
+
+---
+
+## Installation
 
 ```bash
 npm install -g agentic-kdd
 ```
 
-## Usage
+Requires Node.js 18+.
+
+---
 
-### Initialize a project
+## Setup
 
 ```bash
 cd your-project
 akdd init
 ```
 
-Detects your stack, asks 3 questions, and installs Agentic KDD.
-Then open the project in Cursor or Claude Code and type:
+That's it. Agentic KDD detects your stack (Node.js, Python, PHP), installs `.agentic/`, injects the `dev:kdd` script, and configures the pipeline.
 
+For brownfield projects (existing codebase):
+
+```bash
+akdd onboard
 ```
-aa: [your task]
+
+Scans your project, maps the stack, suggests a first small task, and pre-populates memory with what it finds.
+
+---
+
+## Usage
+
+Every task goes through `aa:`:
+
+```
+aa: implement the clients module with CRUD and tenant isolation
+```
+
+The pipeline runs automatically:
+
 ```
+① Analyst     — reads memory, recalls patterns and past errors
+② Spec Gate   — blocks if prompt contradicts HIGH-confidence rules
+③ Security Gate — checks CRITICAL/SENSITIVE files before build
+④ Regression Check — verifies changeset won't break protected behaviors
+⑤ Build       — implementation
+⑥ TDD Gate    — runs tests, self-heals up to 3 iterations
+⑦ QA          — validates against spec and memory
+⑧ Preservation Gate — verifies contracts
+⑨ Regression Register — snapshots healthy behaviors
+⑩ Memory      — writes errors, patterns and decisions
+⑪ Creative    — detects improvement opportunities
+```
+
+---
 
-### Update to latest version
+## CLI commands
 
 ```bash
-akdd update
+akdd init              # Install in a new project
+akdd onboard           # Analyze an existing project (brownfield)
+akdd update            # Pull latest from GitHub
+akdd contracts         # Contract Guard status
+akdd contracts list    # List all contracts
+akdd graph             # Knowledge graph state
+akdd metrics           # Project metrics
+akdd health            # System health check
+akdd analyze           # Cross-artifact consistency check
 ```
 
-Updates agent instructions to the latest version.
-Your memory, config, and knowledge base are never touched.
+---
 
-## What gets installed
+## What's in the repo
 
 ```
-your-project/
-├── CLAUDE.md                    ← Claude Code reads this automatically
-├── _LOCKS.md                    ← parallel instance coordination
-├── _output/                     ← auto-generated decision logs
-├── .cursor/rules/agentic.mdc    ← Cursor reads this automatically
-└── .agentic/
-    ├── config.md                ← auto-configured for your stack
-    ├── PLAN.md                  ← active task tracker
-    ├── memoria/                 ← KDD knowledge base
-    │   ├── trabajo.md
-    │   ├── errores.md
-    │   ├── patrones.md
-    │   └── decisiones.md
-    ├── agentes/                 ← 8 agent instruction files
-    └── conocimiento/            ← drop your project docs here
+.agentic/
+├── agentes/           # Role instructions (Orchestrator, Analyst, Back, Front, QA, Memory)
+├── grafo/             # Gate modules (tdd-gate, spec-gate, security-gate, regression-guard, contract-guard)
+├── memoria/           # KDD memory files (errors, patterns, decisions, work)
+├── config.md          # Project configuration
+└── PLAN.md            # Active task
+
+CLAUDE.md              # Pipeline rules for Claude Code
+.cursor/rules/         # Pipeline rules for Cursor
 ```
 
-## Requirements
+---
+
+## How it compares
+
+| | OpenSpec | Spec-Kit | Agentic KDD |
+|---|---|---|---|
+| Spec violation gate | ❌ | ❌ | ✅ blocks before build |
+| Security gate | ❌ | ❌ | ✅ blocks before build |
+| Error memory (KDD) | ❌ | ❌ | ✅ persists across sessions |
+| TDD self-healing loop | ❌ | Partial | ✅ deterministic, 3 iterations |
+| Regression protection | ❌ | ❌ | ✅ cascade-tested |
+| Contract escalation | ❌ | ❌ | ✅ candidate → verified → protected |
+| Python support | ❌ | ✅ | ✅ pytest + FastAPI |
+| Brownfield onboarding | ✅ | Partial | ✅ akdd onboard |
+| npm install | ✅ | ❌ | ✅ |
+| MCP tools | 25+ | — | 59 |
+
+---
 
-- Node.js 18+
-- curl (pre-installed on Mac/Linux; on Windows use Git Bash)
+## Stack support
 
-## Links
+- **Node.js** — Next.js, Express, Fastify, NestJS + Jest/Vitest
+- **Python** — FastAPI, Django, Flask + pytest
+- **PHP** — Laravel + PHPUnit
 
-- [GitHub](https://github.com/Adrianlpz211/Agentic-KDD)
-- [Documentation](https://github.com/Adrianlpz211/Agentic-KDD/blob/main/docs/kdd-methodology.md)
+---
 
 ## License
 
-MIT
+MIT — Adrián López ([@Adrianlpz211](https://github.com/Adrianlpz211))

package/akdd-analyze.cjs

@@ -0,0 +1,319 @@
+'use strict';
+/**
+ * Agentic KDD — Analyzer v1.0
+ * Verificación de consistencia cross-artefacto.
+ * Compara specs, código y tests para detectar inconsistencias antes de que
+ * el agente las encuentre en producción.
+ *
+ * Uso:
+ *   node .agentic/grafo/akdd-analyze.cjs run        → análisis completo
+ *   node .agentic/grafo/akdd-analyze.cjs contracts  → verifica contratos vs tests
+ *   node .agentic/grafo/akdd-analyze.cjs memory     → verifica memoria vs código
+ *   node .agentic/grafo/akdd-analyze.cjs spec       → verifica spec vs código
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT         = process.cwd();
+const AGENTIC_DIR  = path.join(ROOT, '.agentic');
+const MEMORIA_DIR  = path.join(AGENTIC_DIR, 'memoria');
+const CONFIG_FILE  = path.join(AGENTIC_DIR, 'config.md');
+const SPECS_DIR    = path.join(AGENTIC_DIR, 'specs');
+
+// ── Findings ──────────────────────────────────────────────────────────────────
+
+const findings = [];
+
+function addFinding(severity, category, message, suggestion) {
+  findings.push({ severity, category, message, suggestion });
+}
+
+// ── Check 1: Contratos vs test files ─────────────────────────────────────────
+
+function checkContractsVsTests() {
+  // Open the SQLite DB if available
+  const dbPath = path.join(AGENTIC_DIR, 'memoria.db');
+  if (!require('fs').existsSync(dbPath)) {
+    addFinding('INFO', 'contracts', 'memoria.db no encontrada — sin contratos que verificar', 'Corre akdd init y algunos ciclos aa:');
+    return;
+  }
+
+  let db;
+  try {
+    const projNodeModules = path.join(ROOT, 'node_modules');
+    if (!module.paths.includes(projNodeModules)) module.paths.unshift(projNodeModules);
+    db = new (require('better-sqlite3'))(dbPath);
+  } catch(e) {
+    addFinding('WARN', 'contracts', 'No se pudo abrir memoria.db: ' + e.message, 'Verifica que better-sqlite3 está instalado');
+    return;
+  }
+
+  try {
+    const contracts = db.prepare("SELECT * FROM verified_contracts WHERE status != 'invalidated'").all();
+
+    if (contracts.length === 0) {
+      addFinding('INFO', 'contracts', 'Sin contratos registrados aún', 'Corre ciclos aa: para acumular contratos');
+      return;
+    }
+
+    // Check each contract's test file still exists
+    for (const c of contracts) {
+      if (c.test_file && c.test_file !== 'npm test' && c.test_file !== 'pytest') {
+        const testPath = path.join(ROOT, c.test_file);
+        if (!fs.existsSync(testPath)) {
+          addFinding('HIGH', 'contracts',
+            `Contrato [${c.id}] referencia "${c.test_file}" que ya no existe`,
+            `Corre akdd contracts verify para actualizar el contrato`);
+        }
+      }
+
+      // Warn on stale protected contracts
+      if (c.status === 'protected' && c.last_verified) {
+        const days = Math.floor((Date.now() - new Date(c.last_verified).getTime()) / 86400000);
+        if (days > 30) {
+          addFinding('WARN', 'contracts',
+            `Contrato PROTECTED [${c.module}] no verificado en ${days} días`,
+            `Corre akdd contracts gate para re-verificar`);
+        }
+      }
+    }
+
+    const protected_ = contracts.filter(c => c.status === 'protected').length;
+    const verified   = contracts.filter(c => c.status === 'verified').length;
+    addFinding('INFO', 'contracts',
+      `${contracts.length} contratos: ${protected_} PROTECTED, ${verified} VERIFIED`,
+      null);
+
+  } catch(e) {
+    addFinding('WARN', 'contracts', 'Error leyendo contratos: ' + e.message, null);
+  } finally {
+    db.close();
+  }
+}
+
+// ── Check 2: Memoria vs código actual ────────────────────────────────────────
+
+function checkMemoryVsCode() {
+  const erroresFile = path.join(MEMORIA_DIR, 'errores.md');
+  const patronesFile= path.join(MEMORIA_DIR, 'patrones.md');
+
+  if (!fs.existsSync(erroresFile) && !fs.existsSync(patronesFile)) {
+    addFinding('INFO', 'memory', 'Archivos de memoria no encontrados', 'Corre akdd init');
+    return;
+  }
+
+  // Check patrones.md for HIGH-confidence rules and verify they're not violated in code
+  if (fs.existsSync(patronesFile)) {
+    const patrones = fs.readFileSync(patronesFile, 'utf8');
+    const highPatterns = patrones.match(/###[^\n]+\n[\s\S]*?\*\*confianza\*\*:\s*ALTA[\s\S]*?(?=###|$)/gi) || [];
+
+    // Basic structural checks on source files
+    const srcFiles = findSourceFiles(ROOT);
+
+    for (const pattern of highPatterns) {
+      const titleMatch = pattern.match(/###\s+(.+)/);
+      const ruleMatch  = pattern.match(/\*\*regla\*\*:\s*(.+)/i);
+      if (!titleMatch || !ruleMatch) continue;
+
+      const rule = ruleMatch[1].toLowerCase();
+
+      // Check: if rule mentions "tenant" or "agency_id", verify files filter by it
+      if ((rule.includes('tenant') || rule.includes('agency_id')) && srcFiles.length > 0) {
+        const routeFiles = srcFiles.filter(f => f.includes('route') || f.includes('router') || f.includes('api'));
+        const violations = routeFiles.filter(f => {
+          const content = safeRead(f);
+          return content && content.includes('findMany') && !content.includes('agency_id') &&
+                 !content.includes('tenant') && !content.includes('TESTING');
+        });
+        if (violations.length > 0) {
+          addFinding('HIGH', 'memory',
+            `Patrón HIGH "${titleMatch[1]}" puede estar violado en: ${violations.slice(0,3).map(f => path.relative(ROOT,f)).join(', ')}`,
+            `Revisar manualmente — patrón: ${rule}`);
+        }
+      }
+    }
+
+    addFinding('INFO', 'memory', `${highPatterns.length} patrones HIGH verificados contra código`, null);
+  }
+
+  // Check errores.md size
+  if (fs.existsSync(erroresFile)) {
+    const errLines = fs.readFileSync(erroresFile, 'utf8').split('\n').filter(l => l.startsWith('### ')).length;
+    if (errLines > 50) {
+      addFinding('WARN', 'memory',
+        `errores.md tiene ${errLines} entradas — puede degradar el contexto del agente`,
+        `Corre: node .agentic/grafo/mem-curator.cjs run`);
+    }
+  }
+}
+
+// ── Check 3: Config vs stack real ────────────────────────────────────────────
+
+function checkConfigVsStack() {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    addFinding('HIGH', 'config', 'config.md no encontrado', 'Corre akdd init');
+    return;
+  }
+
+  const config = fs.readFileSync(CONFIG_FILE, 'utf8');
+
+  // Check test command is configured
+  const testMatch = config.match(/^\s*test:\s*(.+)$/m);
+  if (!testMatch || testMatch[1].trim() === '—' || testMatch[1].trim() === '') {
+    addFinding('HIGH', 'config',
+      'Comando de tests no configurado en config.md',
+      'Agrega: test: npm test  (o el comando de tu stack)');
+  } else {
+    addFinding('INFO', 'config', `Comando de tests: ${testMatch[1].trim()}`, null);
+  }
+
+  // Check Python project has test command pointing to pytest
+  const hasPython = fs.existsSync(path.join(ROOT, 'backend', 'requirements.txt')) ||
+                    fs.existsSync(path.join(ROOT, 'requirements.txt'));
+  if (hasPython && testMatch && !testMatch[1].includes('pytest')) {
+    addFinding('WARN', 'config',
+      'Proyecto Python detectado pero test: no usa pytest',
+      `Cambia a: test: cd backend && py -3.13 -m pytest -x -v`);
+  }
+
+  // Check DESIGN_SYSTEM
+  const hasDesignSystem = fs.existsSync(path.join(ROOT, 'DESIGN_SYSTEM.md')) ||
+                          fs.existsSync(path.join(ROOT, '.agentic', 'DESIGN_SYSTEM.md'));
+  if (!hasDesignSystem) {
+    addFinding('INFO', 'config', 'DESIGN_SYSTEM.md no encontrado',
+      'Opcional: crea DESIGN_SYSTEM.md para que el agente Front tenga referencia de tokens');
+  }
+}
+
+// ── Check 4: Specs vs código ──────────────────────────────────────────────────
+
+function checkSpecsVsCode() {
+  if (!fs.existsSync(SPECS_DIR)) {
+    addFinding('INFO', 'specs', 'No hay specs registradas aún', 'Se crean automáticamente durante ciclos aa:');
+    return;
+  }
+
+  const specFiles = fs.readdirSync(SPECS_DIR).filter(f => f.endsWith('.md'));
+  if (specFiles.length === 0) {
+    addFinding('INFO', 'specs', 'Directorio specs vacío', null);
+    return;
+  }
+
+  addFinding('INFO', 'specs', `${specFiles.length} specs encontradas`, null);
+
+  // Check specs for unresolved TODOs
+  for (const specFile of specFiles) {
+    const content = safeRead(path.join(SPECS_DIR, specFile)) || '';
+    const todos   = (content.match(/\bTODO\b|\bPENDING\b|\bFIXME\b/gi) || []).length;
+    if (todos > 0) {
+      addFinding('WARN', 'specs',
+        `${specFile} tiene ${todos} TODOs/PENDINGs sin resolver`,
+        `Revisar y actualizar o eliminar entradas obsoletas`);
+    }
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function findSourceFiles(root, extensions = ['.ts', '.tsx', '.js', '.py']) {
+  const results = [];
+  const skip = new Set(['node_modules', '.agentic', '.git', '__pycache__', '.next', 'dist', 'build']);
+
+  function walk(dir) {
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (skip.has(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (extensions.some(e => entry.name.endsWith(e))) results.push(full);
+      }
+    } catch {}
+  }
+
+  walk(root);
+  return results;
+}
+
+function safeRead(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return null; }
+}
+
+// ── Report printer ────────────────────────────────────────────────────────────
+
+function printReport() {
+  console.log('\n══════════════════════════════════════════════════');
+  console.log('  🔍 Agentic KDD — Analyzer');
+  console.log('══════════════════════════════════════════════════');
+
+  const bySeverity = { HIGH: [], WARN: [], INFO: [] };
+  for (const f of findings) {
+    (bySeverity[f.severity] || bySeverity.INFO).push(f);
+  }
+
+  if (bySeverity.HIGH.length > 0) {
+    console.log('\n  🔴 HIGH — requieren atención:');
+    for (const f of bySeverity.HIGH) {
+      console.log(`\n  [${f.category.toUpperCase()}] ${f.message}`);
+      if (f.suggestion) console.log(`  → ${f.suggestion}`);
+    }
+  }
+
+  if (bySeverity.WARN.length > 0) {
+    console.log('\n  🟠 WARN — revisar:');
+    for (const f of bySeverity.WARN) {
+      console.log(`\n  [${f.category.toUpperCase()}] ${f.message}`);
+      if (f.suggestion) console.log(`  → ${f.suggestion}`);
+    }
+  }
+
+  if (bySeverity.INFO.length > 0) {
+    console.log('\n  ✅ INFO:');
+    for (const f of bySeverity.INFO) {
+      console.log(`  [${f.category.toUpperCase()}] ${f.message}`);
+    }
+  }
+
+  const total = findings.length;
+  const issues = bySeverity.HIGH.length + bySeverity.WARN.length;
+  console.log(`\n  Total: ${total} checks | Problemas: ${issues}`);
+
+  if (issues === 0) {
+    console.log('  ✅ Todo consistente — el proyecto está en buen estado.');
+  } else if (bySeverity.HIGH.length > 0) {
+    console.log('  ⛔ Hay inconsistencias críticas — resolver antes del próximo ciclo aa:');
+    process.exit(1);
+  } else {
+    console.log('  ⚠️  Hay advertencias — revisar cuando sea posible.');
+  }
+
+  console.log('══════════════════════════════════════════════════\n');
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const cmd = process.argv[2] || 'run';
+
+  if (cmd === 'run') {
+    checkContractsVsTests();
+    checkMemoryVsCode();
+    checkConfigVsStack();
+    checkSpecsVsCode();
+  } else if (cmd === 'contracts') {
+    checkContractsVsTests();
+  } else if (cmd === 'memory') {
+    checkMemoryVsCode();
+  } else if (cmd === 'spec') {
+    checkSpecsVsCode();
+  } else if (cmd === 'config') {
+    checkConfigVsStack();
+  } else {
+    console.log('Uso: node akdd-analyze.cjs [run|contracts|memory|spec|config]');
+    process.exit(0);
+  }
+
+  printReport();
+}
+
+module.exports = { checkContractsVsTests, checkMemoryVsCode, checkConfigVsStack, checkSpecsVsCode };

package/bin/akdd.js

@@ -3,6 +3,7 @@
 
 const { init }      = require('../src/init');
 const { update }    = require('../src/update');
+const { onboard }   = require('../src/onboard');
 const { graph }     = require('../src/graph');
 const { dashboard } = require('../src/dashboard');
 const { analyze }   = require('../src/analyze');
@@ -24,6 +25,8 @@ const HELP = `
   Setup:
     akdd init              Install Agentic KDD in the current project
     akdd update            Update agents + engine (memory stays intact)
+    akdd onboard           Analyze existing project + pre-populate memory
+    akdd analyze           Cross-artifact consistency check
     akdd health            System health check — what's configured, what's missing
     akdd health --fix      Auto-fix common issues
 
@@ -155,6 +158,8 @@ switch (command) {
 
   case 'init':    init(); break;
   case 'update':  update(); break;
+  case 'onboard': onboard(); break;
+  case 'analyze': runModule('akdd-analyze.cjs', args[0] || 'run'); break;
   case 'analyze': analyze(); break;
 
   // ── v3.0: Health ──────────────────────────────────────────────────────