agentic-kdd 3.5.6 → 3.5.8

package/templates/.agentic/DESIGN_SYSTEM.fastapi.md

@@ -0,0 +1,109 @@
+# DESIGN_SYSTEM.md — API Contract Reference
+<!-- Agentic KDD — API Design System -->
+<!-- El agente Back lee este archivo antes de cualquier tarea de API -->
+
+## Stack de Backend
+- Framework: (completar: FastAPI / Express / Fastify / NestJS)
+- ORM: (completar: SQLAlchemy / Prisma / TypeORM)
+- Auth: JWT (access 15min + refresh 7d)
+- DB: (completar: PostgreSQL / MySQL / SQLite)
+
+## Convenciones de API
+
+### Rutas
+```
+GET    /recursos/          → listar (con filtros y paginación)
+POST   /recursos/          → crear
+GET    /recursos/{id}      → obtener por ID
+PUT    /recursos/{id}      → actualizar completo
+PATCH  /recursos/{id}      → actualizar parcial
+DELETE /recursos/{id}      → eliminar (soft delete preferido)
+```
+
+### Respuestas de éxito
+```json
+// Lista
+{
+  "data": [...],
+  "total": 100,
+  "page": 1,
+  "per_page": 20
+}
+
+// Item único
+{
+  "id": "uuid",
+  "...campos": "..."
+}
+
+// Creación exitosa → 201
+// Actualización exitosa → 200
+// Sin contenido → 204
+```
+
+### Respuestas de error
+```json
+{
+  "detail": "Mensaje de error legible",
+  "code": "ERROR_CODE_SNAKE_CASE"
+}
+```
+
+### Códigos de error estándar
+- 400 Bad Request — validación fallida
+- 401 Unauthorized — sin token o token inválido
+- 403 Forbidden — token válido pero sin permiso
+- 404 Not Found — recurso no existe
+- 409 Conflict — duplicado o violación de constraint
+- 422 Unprocessable Entity — pydantic validation error
+- 500 Internal Server Error — error inesperado
+
+## Reglas de negocio críticas
+<!-- COMPLETAR con las reglas de tu dominio -->
+<!-- Ejemplo: -->
+```
+OVERTIME_THRESHOLD = 8       # horas por día antes de overtime
+OVERTIME_MULTIPLIER = 1.5    # multiplicador de tarifa
+INVOICE_DUE_DAYS = 30        # días de plazo en facturas
+INVOICE_PREFIX = "AGY"       # prefijo de números de factura
+```
+
+## Multi-tenancy
+- Toda tabla de datos tiene `agency_id` (o equivalente)
+- Toda query DEBE filtrar por `agency_id` del token JWT
+- Nunca exponer datos de un tenant a otro
+- El campo `agency_id` en requests del body se IGNORA — siempre del token
+
+## Paginación
+```
+?page=1&per_page=20          → paginación estándar
+?cursor=xxx                   → cursor-based (preferido para listas grandes)
+?search=texto                 → búsqueda fulltext
+?sort=campo&order=asc|desc   → ordenamiento
+```
+
+## Autenticación
+```
+Authorization: Bearer <access_token>
+X-Refresh-Token: <refresh_token>   (solo en /auth/refresh)
+```
+
+## Convenciones de naming
+- Rutas: snake_case y plural → /agency_users/
+- Campos en JSON: snake_case
+- IDs: UUID v4
+- Fechas: ISO 8601 → "2026-06-27T18:00:00Z"
+- Booleanos: is_active, has_*, can_*
+
+## Campos auditables estándar
+Toda tabla de datos debe tener:
+```
+id          UUID PRIMARY KEY
+created_at  TIMESTAMP WITH TIME ZONE
+updated_at  TIMESTAMP WITH TIME ZONE
+is_active   BOOLEAN DEFAULT true
+```
+
+---
+> Actualiza este archivo cuando cambies la API o las reglas de negocio.
+> El agente Back lo lee antes de cada tarea.

package/templates/.agentic/DESIGN_SYSTEM.nextjs.md

@@ -0,0 +1,91 @@
+# DESIGN_SYSTEM.md
+<!-- Agentic KDD — Design System Reference -->
+<!-- El agente Front lee este archivo antes de cualquier tarea de UI -->
+
+## Stack de UI
+- Framework: Next.js 14 (App Router)
+- Estilos: Tailwind CSS
+- Componentes: (completar: shadcn/ui, Radix, custom)
+- Iconos: (completar: lucide-react, heroicons, etc.)
+- Fuentes: (completar)
+
+## Paleta de colores
+<!-- Rellenar con los colores reales del proyecto -->
+```
+Primary:    #000000   (completar)
+Secondary:  #000000   (completar)
+Background: #FFFFFF   (completar)
+Surface:    #F5F5F5   (completar)
+Border:     #E5E5E5   (completar)
+Text:       #111111   (completar)
+Muted:      #6B7280   (completar)
+Danger:     #EF4444
+Success:    #22C55E
+Warning:    #F59E0B
+```
+
+## Tipografía
+```
+Font base:  (completar)
+Scale:
+  xs:   12px
+  sm:   14px
+  base: 16px
+  lg:   18px
+  xl:   20px
+  2xl:  24px
+  3xl:  30px
+```
+
+## Espaciado
+Usa la escala de Tailwind. Unidad base: 4px (= 1 unidad Tailwind).
+
+## Componentes base
+<!-- Documenta los componentes compartidos del proyecto -->
+
+### Button
+```tsx
+// Variantes disponibles: default, outline, ghost, destructive
+<Button variant="default" size="md">Label</Button>
+```
+
+### Card
+```tsx
+<Card>
+  <CardHeader><CardTitle>Título</CardTitle></CardHeader>
+  <CardContent>Contenido</CardContent>
+</Card>
+```
+
+### Form inputs
+```tsx
+<Input type="text" placeholder="..." />
+<Textarea placeholder="..." />
+<Select>...</Select>
+```
+
+## Convenciones de layout
+- Container max-width: (completar)
+- Sidebar: (completar) px
+- Padding de página: p-6 (desktop), p-4 (mobile)
+- Gap estándar en grids: gap-4 o gap-6
+
+## Convenciones de naming
+- Componentes: PascalCase
+- Páginas (App Router): page.tsx en carpeta del segmento
+- Layouts: layout.tsx
+- Clases Tailwind: orden → layout → spacing → typography → colors → states
+
+## Estados de loading / error
+- Skeleton: usar componente Skeleton durante carga
+- Error: mostrar mensaje + botón retry
+- Empty state: ilustración + texto descriptivo + CTA
+
+## Accesibilidad mínima
+- Todos los inputs tienen label visible o aria-label
+- Botones de icono tienen aria-label
+- Contraste mínimo: 4.5:1 para texto normal
+
+---
+> Actualiza este archivo cuando cambies el design system.
+> El agente Front lo lee antes de cada tarea de UI.

package/templates/.agentic/grafo/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 };