@girardelli/architect 5.0.0 → 6.0.0

package/src/core/agent-generator/enrichers/module-extractor.ts

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { AnalysisReport } from '../../types/core.js';
+import { ModuleDetail, DetectedEndpoint } from '../types/domain.js';
+import { EnrichedTemplateContext } from '../types/template.js';
+
+import { LayerClassifier } from './layer-classifier.js';
+import { DescriptionGenerator } from './description-generator.js';
+import { AnalysisHelpers } from './analysis-helpers.js';
+
+export class ModuleExtractor {
+  private layerClassifier = new LayerClassifier();
+  private descriptionGenerator = new DescriptionGenerator();
+  private analysisHelpers = new AnalysisHelpers();
+
+public extractModules(report: AnalysisReport, projectPath: string): ModuleDetail[] {
+    const modules = new Map<string, ModuleDetail>();
+    const nodes = report.dependencyGraph.nodes;
+
+    for (const filePath of nodes) {
+      const moduleName = this.inferModuleName(filePath);
+      if (!moduleName) continue;
+
+      if (!modules.has(moduleName)) {
+        modules.set(moduleName, {
+          name: moduleName,
+          path: this.inferModulePath(filePath, moduleName),
+          files: [],
+          fileCount: 0,
+          lineCount: 0,
+          description: '',
+          hasTests: false,
+          testFiles: [],
+          entities: [],
+          controllers: [],
+          services: [],
+          layer: this.layerClassifier.inferFileLayer(filePath),
+        });
+      }
+
+      const mod = modules.get(moduleName)!;
+      mod.files.push(filePath);
+      mod.fileCount++;
+
+      // v3.1: Count real lines
+      mod.lineCount += this.analysisHelpers.countFileLines(projectPath, filePath);
+
+      const lower = filePath.toLowerCase();
+      if (this.layerClassifier.isTestFile(lower)) {
+        mod.hasTests = true;
+        mod.testFiles.push(filePath);
+      }
+      if (this.layerClassifier.isEntityFile(lower)) {
+        const entityName = this.layerClassifier.extractEntityName(filePath);
+        if (entityName) mod.entities.push(entityName);
+      }
+      if (this.layerClassifier.isControllerOrRouteFile(lower)) {
+        mod.controllers.push(filePath);
+      }
+      if (this.layerClassifier.isServiceFile(lower)) {
+        mod.services.push(filePath);
+      }
+    }
+
+    // Enrich with descriptions from project summary
+    if (report.projectSummary?.modules) {
+      for (const summaryMod of report.projectSummary.modules) {
+        const key = summaryMod.name.toLowerCase();
+        for (const [modName, mod] of modules) {
+          if (modName.toLowerCase().includes(key) || key.includes(modName.toLowerCase())) {
+            mod.description = summaryMod.description;
+            break;
+          }
+        }
+      }
+    }
+
+    // v3.1: Smart descriptions for modules without one
+    for (const mod of modules.values()) {
+      if (!mod.description) {
+        mod.description = this.descriptionGenerator.generateSmartDescription(mod);
+      }
+    }
+
+    return [...modules.values()].sort((a, b) => b.fileCount - a.fileCount);
+  }
+
+
+public inferModuleName(filePath: string): string | null {
+    const parts = filePath.split('/');
+    const lower = filePath.toLowerCase();
+
+    // Skip __init__.py / index files as standalone modules
+    const fileName = parts[parts.length - 1].toLowerCase();
+    if (fileName === '__init__.py' || fileName === 'index.ts' || fileName === 'index.js' || fileName === 'index.py') {
+      // Only process if it's in a meaningful directory
+    }
+
+    // ── Strategy 1: Explicit module markers ──
+    const moduleMarkers = ['modules', 'features', 'apps', 'domains', 'packages', 'components', 'pages', 'bundles'];
+    for (let i = 0; i < parts.length; i++) {
+      if (moduleMarkers.includes(parts[i].toLowerCase()) && parts[i + 1]) {
+        return parts[i + 1];
+      }
+    }
+
+    // ── Strategy 2: Clean Architecture / DDD layers ──
+    const cleanArchLayers = new Set([
+      'domain', 'application', 'infrastructure', 'presentation',
+      'core', 'adapters', 'ports', 'usecases', 'use_cases',
+    ]);
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (cleanArchLayers.has(parts[i].toLowerCase()) && parts[i + 1]) {
+        const nextDir = parts[i + 1].toLowerCase();
+        const subLayers = new Set([
+          'services', 'entities', 'models', 'repositories', 'interfaces',
+          'value_objects', 'events', 'exceptions', 'enums', 'dto', 'dtos',
+          'controllers', 'views', 'routes', 'api', 'workers', 'consumers',
+          'persistence', 'storage', 'extraction', 'agents', 'adapters',
+          'mappers', 'factories', 'providers', 'guards', 'middleware',
+          'dependencies', 'schemas', 'serializers', 'signals', 'tasks',
+          'commands', 'queries', 'handlers', 'listeners',
+        ]);
+
+        if (subLayers.has(nextDir)) {
+          if (parts[i + 2] && !parts[i + 2].includes('.')) {
+            return parts[i + 2]; // e.g., infrastructure/extraction/extractors → extractors
+          }
+          return `${parts[i]}/${parts[i + 1]}`;
+        }
+
+        if (!this.layerClassifier.isGenericDir(nextDir) && nextDir.length > 2 && !nextDir.startsWith('__')) {
+          return parts[i + 1];
+        }
+      }
+    }
+
+    // ── Strategy 3: Django apps pattern ──
+    const djangoMarkers = ['views.py', 'models.py', 'urls.py', 'serializers.py', 'admin.py', 'apps.py', 'forms.py'];
+    if (djangoMarkers.some(m => lower.endsWith(m))) {
+      const parentDir = parts[parts.length - 2];
+      if (parentDir && !this.layerClassifier.isGenericDir(parentDir.toLowerCase())) {
+        return parentDir;
+      }
+    }
+
+    // ── Strategy 4: Java/PHP package-based ──
+    const javaPackageMarkers = ['com', 'org', 'net', 'io', 'br'];
+    for (let i = 0; i < parts.length; i++) {
+      if (javaPackageMarkers.includes(parts[i].toLowerCase()) && parts[i + 2]) {
+        return parts[i + 2];
+      }
+    }
+
+    // PHP namespace: App/Http/Controllers/UserController.php → user
+    if (lower.includes('/http/controllers/') || lower.includes('/http/requests/')) {
+      const parentDir = parts[parts.length - 2];
+      if (parentDir && parentDir.toLowerCase() !== 'controllers' && parentDir.toLowerCase() !== 'requests') {
+        return parentDir;
+      }
+      const baseName = parts[parts.length - 1]
+        .replace(/\.[^.]+$/, '')
+        .replace(/(Controller|Request|Resource|Policy|Observer|Event)$/i, '');
+      if (baseName.length > 2) return baseName;
+    }
+
+    // ── Strategy 5: Go package ──
+    if (lower.endsWith('.go')) {
+      const parentDir = parts[parts.length - 2];
+      if (parentDir && !this.layerClassifier.isGenericDir(parentDir.toLowerCase()) && parentDir !== 'cmd' && parentDir !== 'internal' && parentDir !== 'pkg') {
+        return parentDir;
+      }
+    }
+
+    // ── Strategy 6: Fallback — walk from end, find first non-generic dir ──
+    const extraGenericForFallback = new Set(['__pycache__', 'node_modules', 'dist', 'build', '.git', 'vendor', 'target']);
+    for (let i = parts.length - 2; i >= 0; i--) {
+      const dir = parts[i].toLowerCase();
+      if (
+        !this.layerClassifier.isGenericDir(dir) &&
+        !extraGenericForFallback.has(dir) &&
+        dir.length > 2 &&
+        !dir.startsWith('.') &&
+        !dir.startsWith('__')
+      ) {
+        return parts[i];
+      }
+    }
+
+    return null;
+  }
+
+
+public inferModulePath(filePath: string, moduleName: string): string {
+    const idx = filePath.toLowerCase().indexOf(moduleName.toLowerCase());
+    if (idx >= 0) {
+      return filePath.substring(0, idx + moduleName.length);
+    }
+    return filePath.split('/').slice(0, -1).join('/');
+  }
+
+
+}

package/src/core/agent-generator/framework-detector.ts

@@ -0,0 +1,66 @@
+import { AnalysisReport } from '../types/core.js';
+import { FrameworkInfo, DetectedToolchain } from './types/stack.js';
+import { PythonDetector } from './detectors/python-detector.js';
+import { NodeDetector } from './detectors/node-detector.js';
+import { JavaDetector } from './detectors/java-detector.js';
+import { PhpDetector } from './detectors/php-detector.js';
+import { GoDetector } from './detectors/go-detector.js';
+import { RubyDetector } from './detectors/ruby-detector.js';
+import { DartDetector } from './detectors/dart-detector.js';
+import { RustDetector } from './detectors/rust-detector.js';
+import { ToolchainDetector } from './detectors/toolchain-detector.js';
+import { StructureDetector } from './detectors/structure-detector.js';
+
+/**
+ * FrameworkDetector — Detects actual frameworks and toolchain from dependency files.
+ * Re-architected as a Strategy/Registry Facade.
+ */
+export class FrameworkDetector {
+  private detectors = [
+    new PythonDetector(),
+    new NodeDetector(),
+    new JavaDetector(),
+    new PhpDetector(),
+    new GoDetector(),
+    new RubyDetector(),
+    new DartDetector(),
+    new RustDetector()
+  ];
+  private toolchainDetector = new ToolchainDetector();
+  private structureDetector = new StructureDetector();
+
+  detect(projectPath: string, report: AnalysisReport): {
+    frameworks: FrameworkInfo[];
+    primaryFramework: FrameworkInfo | null;
+    toolchain: DetectedToolchain;
+    projectStructure: 'clean-architecture' | 'mvc' | 'modular' | 'flat' | 'monorepo' | 'unknown';
+  } {
+    const frameworks: FrameworkInfo[] = [];
+
+    // Run all detectors
+    for (const detector of this.detectors) {
+      detector.detect(projectPath, frameworks);
+    }
+
+    // Deduplicate by name
+    const seen = new Set<string>();
+    const unique = frameworks.filter(f => {
+      if (seen.has(f.name)) return false;
+      seen.add(f.name);
+      return true;
+    });
+
+    // Sort: web frameworks first, then by confidence
+    unique.sort((a, b) => {
+      if (a.category === 'web' && b.category !== 'web') return -1;
+      if (a.category !== 'web' && b.category === 'web') return 1;
+      return b.confidence - a.confidence;
+    });
+
+    const primaryFramework = unique.find(f => f.category === 'web') || null;
+    const toolchain = this.toolchainDetector.detectToolchain(projectPath, report, primaryFramework, unique);
+    const projectStructure = this.structureDetector.detectProjectStructure(report);
+
+    return { frameworks: unique, primaryFramework, toolchain, projectStructure };
+  }
+}

package/src/core/agent-generator/index.ts

@@ -0,0 +1,55 @@
+import { join } from "path";
+import { existsSync } from "fs";
+import { AnalysisReport } from '../types/core.js';
+import { RefactoringPlan } from '../types/rules.js';
+import { StackInfo, FrameworkInfo, DetectedToolchain } from './types/stack.js';
+import { AgentAuditFinding, AgentItem, AgentItemStatus, AgentSuggestion, AgentGeneratorConfig, DEFAULT_AGENT_CONFIG } from './types/agent.js';
+import { TemplateContext, EnrichedTemplateContext } from './types/template.js';
+import { DomainInsights, ModuleDetail, DetectedEndpoint } from './types/domain.js';
+
+import { ContextBuilder } from "./engines/context-builder.js";
+import { AuditEngine } from "./engines/audit-engine.js";
+import { SuggestionEngine } from "./engines/suggestion-engine.js";
+import { GenerationEngine } from "./engines/generation-engine.js";
+import { StackDetector } from "./stack-detector.js";
+
+export type { StackInfo, AgentAuditFinding, AgentItem, AgentItemStatus, AgentSuggestion, EnrichedTemplateContext, DomainInsights, ModuleDetail, DetectedEndpoint, FrameworkInfo, DetectedToolchain };
+
+/**
+ * Agent Generator v3.2 — Enterprise-Grade
+ *
+ * Generates or audits .agent/ directories with enterprise-grade
+ * agent frameworks. Delegated to specialized engines.
+ */
+export class AgentGenerator {
+  private stackDetector = new StackDetector();
+  private contextBuilder = new ContextBuilder();
+  private auditEngine = new AuditEngine();
+  private suggestionEngine = new SuggestionEngine();
+  private generationEngine = new GenerationEngine();
+
+  suggest(report: AnalysisReport, plan: RefactoringPlan, projectPath: string): AgentSuggestion {
+    return this.suggestionEngine.suggest(report, plan, projectPath);
+  }
+
+  generate(
+    report: AnalysisReport,
+    plan: RefactoringPlan,
+    projectPath: string,
+    outputDir?: string
+  ): { generated: string[]; audit: AgentAuditFinding[] } {
+    const cleanReport = this.contextBuilder.sanitizeReport(report);
+    const stack = this.stackDetector.detect(cleanReport);
+    const agentDir = outputDir || join(projectPath, '.agent');
+    const isExisting = existsSync(agentDir);
+
+    if (isExisting) {
+      const audit = this.auditEngine.auditExisting(agentDir, stack, cleanReport, plan);
+      const generated = this.generationEngine.generateMissing(agentDir, audit, cleanReport, plan, stack, projectPath);
+      return { generated, audit };
+    }
+
+    const generated = this.generationEngine.generateFull(agentDir, cleanReport, plan, stack, projectPath);
+    return { generated, audit: [] };
+  }
+}

package/src/{agent-generator → core/agent-generator}/stack-detector.ts

@@ -1,5 +1,5 @@
-import { AnalysisReport } from '../types.js';
-import { StackInfo } from './types.js';
+import { AnalysisReport } from '../types/core.js';
+import { StackInfo } from './types/stack.js';
 
 /**
  * Detects the technology stack from an AnalysisReport.

package/src/{agent-generator → core/agent-generator}/templates/core/agents.ts

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 import { crossRef, depthIndicator, depthAtLeast, getEnriched, frameworkBadge, frameworkModuleStructure, frameworkSecurityChecklist, toolchainCommands, projectStructureBadge } from '../template-helpers.js';
 
 /**

package/src/{agent-generator → core/agent-generator}/templates/core/architecture-rules.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates 01-architecture.md — layer rules, dependency direction,

package/src/{agent-generator → core/agent-generator}/templates/core/general-rules.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 import { getEnriched } from '../template-helpers.js';
 
 /**

package/src/{agent-generator → core/agent-generator}/templates/core/hooks-generator.ts

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 import { getEnriched } from '../template-helpers.js';
 
 /**

package/src/{agent-generator → core/agent-generator}/templates/core/index-md.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates enterprise-grade INDEX.md — master navigation guide for the agent framework.

package/src/{agent-generator → core/agent-generator}/templates/core/orchestrator.ts

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 import {
   getEnriched,
   isEnriched,

package/src/{agent-generator → core/agent-generator}/templates/core/preflight.ts

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 import { getEnriched } from '../template-helpers.js';
 
 /**

package/src/{agent-generator → core/agent-generator}/templates/core/quality-gates.ts

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 import { getEnriched, depthAtLeast, complianceBadges, depthIndicator } from '../template-helpers.js';
 
 /**

package/src/{agent-generator → core/agent-generator}/templates/core/security-rules.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates 02-security.md — OWASP rules, input validation, secrets management,

package/src/{agent-generator → core/agent-generator}/templates/core/skills-generator.ts

@@ -1,4 +1,4 @@
-import { EnrichedTemplateContext, TemplateContext } from '../../types.js';
+import { EnrichedTemplateContext, TemplateContext } from '../../types/template.js';
 import { getEnriched } from '../template-helpers.js';
 
 /**

package/src/{agent-generator → core/agent-generator}/templates/core/workflow-fix-bug.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates enterprise-grade fix-bug.md workflow.

package/src/{agent-generator → core/agent-generator}/templates/core/workflow-new-feature.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates enterprise-grade new-feature.md workflow.

package/src/{agent-generator → core/agent-generator}/templates/core/workflow-review.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates enterprise-grade review.md workflow.

package/src/{agent-generator → core/agent-generator}/templates/domain/index.ts

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 
 /**
  * Domain templates — C4, BDD, TDD, ADR, Threat Model.

package/src/core/agent-generator/templates/helpers/base-helpers.ts

@@ -0,0 +1,32 @@
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
+import { FrameworkInfo } from '../../types/stack.js';
+
+export function getEnriched(ctx: TemplateContext): Partial<EnrichedTemplateContext> {
+  if ('domain' in ctx) return ctx as EnrichedTemplateContext;
+  return {};
+}
+
+export function isEnriched(ctx: TemplateContext): ctx is EnrichedTemplateContext {
+  return 'domain' in ctx;
+}
+
+export function depthScale<T>(
+  ctx: TemplateContext,
+  options: {
+    small: T;
+    medium: T;
+    large: T;
+    enterprise: T;
+  },
+): T {
+  const enriched = getEnriched(ctx);
+  const depth = (enriched.projectDepth || 'medium') as 'small' | 'medium' | 'large' | 'enterprise';
+  return options[depth];
+}
+
+export function depthAtLeast(ctx: TemplateContext, minDepth: 'small' | 'medium' | 'large' | 'enterprise'): boolean {
+  const enriched = getEnriched(ctx);
+  const depth = enriched.projectDepth || 'medium';
+  const order = ['small', 'medium', 'large', 'enterprise'];
+  return order.indexOf(depth) >= order.indexOf(minDepth);
+}

package/src/core/agent-generator/templates/helpers/cross-ref-helpers.ts

@@ -0,0 +1,79 @@
+import { TemplateContext } from '../../types/template.js';
+
+export function crossRef(agentId: string, ctx: TemplateContext): string {
+  const { stack } = ctx;
+
+  const agentRelations: Record<string, { id: string; name: string; when: string }[]> = {
+    'backend': [
+      { id: 'database-engineer', name: 'Database Engineer', when: 'Criar/alterar entities, migrations, queries' },
+      { id: 'security-auditor', name: 'Security Auditor', when: 'Novo endpoint, auth flow, dados sensíveis' },
+      { id: 'qa-test', name: 'QA Test Engineer', when: 'Após implementação — plano de testes' },
+      { id: 'tech-debt', name: 'Tech Debt Controller', when: 'Antes de criar novo módulo — verificar débito' },
+    ],
+    'frontend': [
+      { id: 'backend', name: 'Backend Developer', when: 'Antes de integrar — doc de integração obrigatória' },
+      { id: 'qa-test', name: 'QA Test Engineer', when: 'Após implementação — testes e2e' },
+      { id: 'security-auditor', name: 'Security Auditor', when: 'Forms, auth UI, dados sensíveis' },
+    ],
+    'flutter': [
+      { id: 'backend', name: 'Backend Developer', when: 'Antes de integrar — doc de integração obrigatória' },
+      { id: 'qa-test', name: 'QA Test Engineer', when: 'Após implementação — testes de widget e integração' },
+      { id: 'security-auditor', name: 'Security Auditor', when: 'Armazenamento local, biometria, deep links' },
+    ],
+    'database-engineer': [
+      { id: 'backend', name: 'Backend Developer', when: 'Após migration — atualizar entities e queries' },
+      { id: 'security-auditor', name: 'Security Auditor', when: 'Dados sensíveis, PII, encryption at rest' },
+      { id: 'tech-debt', name: 'Tech Debt Controller', when: 'Schema com N+1, índices faltantes' },
+    ],
+    'security-auditor': [
+      { id: 'backend', name: 'Backend Developer', when: 'Falha de segurança em endpoint/service' },
+      { id: 'database-engineer', name: 'Database Engineer', when: 'Encryption at rest, data masking' },
+      { id: 'qa-test', name: 'QA Test Engineer', when: 'Testes de segurança (fuzzing, pentest)' },
+    ],
+    'qa-test': [
+      { id: 'backend', name: 'Backend Developer', when: 'Cobertura insuficiente em services' },
+      { id: 'frontend', name: 'Frontend Developer', when: 'Testes e2e falhando, componentes sem testes' },
+      { id: 'tech-debt', name: 'Tech Debt Controller', when: 'Testes com .skip(), mocks frágeis' },
+    ],
+    'tech-debt': [
+      { id: 'backend', name: 'Backend Developer', when: 'Refatoração de módulo, god class' },
+      { id: 'database-engineer', name: 'Database Engineer', when: 'N+1 queries, índices, schema refactoring' },
+      { id: 'security-auditor', name: 'Security Auditor', when: 'Débito de segurança (dependencies, configs)' },
+    ],
+    'code-review': [
+      { id: 'security-auditor', name: 'Security Auditor', when: 'Review de endpoints, auth, dados sensíveis' },
+      { id: 'qa-test', name: 'QA Test Engineer', when: 'Verificar cobertura e qualidade dos testes' },
+      { id: 'tech-debt', name: 'Tech Debt Controller', when: 'Avaliar impacto em débito técnico' },
+    ],
+    'orchestrator': [
+      { id: 'backend', name: 'Backend Developer', when: 'Features que tocam backend' },
+      { id: 'frontend', name: 'Frontend Developer', when: 'Features que tocam frontend' },
+      { id: 'flutter', name: 'Flutter UI Developer', when: 'Features que tocam app mobile' },
+      { id: 'database-engineer', name: 'Database Engineer', when: 'Features que tocam banco de dados' },
+      { id: 'security-auditor', name: 'Security Auditor', when: 'TODA feature — revisão obrigatória' },
+      { id: 'qa-test', name: 'QA Test Engineer', when: 'TODA feature — plano de testes obrigatório' },
+      { id: 'tech-debt', name: 'Tech Debt Controller', when: 'Antes de nova feature — checar débito' },
+    ],
+  };
+
+  const relations = agentRelations[agentId] || [];
+  const filtered = relations.filter(r => {
+    if (r.id === 'frontend' && !stack.hasFrontend) return false;
+    if (r.id === 'flutter' && !stack.hasMobile) return false;
+    if (r.id === 'database-engineer' && !stack.hasDatabase) return false;
+    return true;
+  });
+
+  if (filtered.length === 0) return '';
+
+  return `
+## 🔗 Cross-References (Agentes Relacionados)
+
+| Agente | Quando Consultar |
+|--------|-----------------|
+${filtered.map(r => `| **${r.name}** | ${r.when} |`).join('\n')}
+
+> **Regra:** Nunca implementar isoladamente. Sempre verificar se o agente relacionado precisa ser consultado.
+`;
+}
+