opencode-telos 1.0.0

package/src/opencode/router/categories.ts

@@ -0,0 +1,192 @@
+/**
+ * Categories — Mapeamento de tools para categorias de intenção.
+ *
+ * Cada tool é classificada em uma ou mais categorias.
+ * O intent classifier usa isso para filtrar tools por categoria.
+ *
+ * Consumido por: intent-classifier.ts, tool-registry.ts
+ * Dependências: tool-taxonomy.ts
+ */
+
+import { STANDALONE_TOOLS, TOOL_TAXONOMY, type ToolCategory } from "./tool-taxonomy.js"
+
+/**
+ * Categorias de intenção do usuário.
+ */
+export type IntentCategory =
+  | "mutation"      // Criar, modificar, remover nós/relações
+  | "query"         // Buscar, consultar, inspecionar o grafo
+  | "workflow"      // Gerenciar changes, aprovações, ciclo de vida
+  | "analysis"      // Análise de impacto, drift, validação
+  | "quality"       // Qualidade de código, métricas, smells
+  | "enterprise"    // Workflows empresariais (migration, security, etc.)
+  | "admin"         // Administração: permissões, sync, cache, snapshots
+  | "discovery"     // Descoberta de requisitos, briefing, perguntas
+  | "implementation" // Geração de código, planejamento, implementação
+  | "info"          // Informação: status, histórico, help
+
+/**
+ * Mapeamento de tools standalone para categorias de intenção.
+ */
+const STANDALONE_CATEGORIES: Record<string, IntentCategory[]> = {
+  // Mutation
+  "sdd.initialize": ["mutation"],
+  "sdd.build_graph": ["mutation", "discovery"],
+  "sdd.update_from_answers": ["mutation", "discovery"],
+  "sdd.discover": ["discovery"],
+
+  // Query
+  "sdd.inspect": ["query"],
+  "sdd.query_graph": ["query"],
+  "sdd.get_context": ["query"],
+
+  // Workflow
+  "sdd.enforce": ["workflow"],
+  "sdd.enforce_rules": ["workflow"],
+  "sdd.full_cycle": ["workflow"],
+  "sdd.create_change": ["workflow"],
+  "sdd.approve_change": ["workflow"],
+  "sdd.complete_change": ["workflow"],
+  "sdd.fail_change": ["workflow"],
+  "sdd.pending_changes": ["workflow", "info"],
+  "sdd.change_history": ["info"],
+  "sdd.impact_report": ["analysis"],
+  "sdd.toggle": ["admin"],
+  "sdd.toggle_status": ["admin"],
+
+  // Analysis
+  "sdd.analyze_impact": ["analysis"],
+  "sdd.validate": ["analysis"],
+  "sdd.detect_drift": ["analysis"],
+  "sdd.drift_signals": ["analysis"],
+  "sdd.anti_patterns": ["analysis"],
+  "sdd.clone_detection": ["analysis"],
+  "sdd.contradictions": ["analysis"],
+  "sdd.coverage": ["analysis"],
+  "sdd.promises": ["analysis"],
+
+  // Implementation
+  "sdd.generate_code": ["implementation"],
+  "sdd.auto_link_tests": ["implementation"],
+
+  // Quality (individual tools, não composits)
+  "sdd.quality": ["quality"],
+  "sdd.constitution": ["analysis"],
+
+  // Enterprise
+  "sdd.bug_fix": ["workflow", "implementation"],
+  "sdd.hotfix": ["workflow", "implementation"],
+  "sdd.refactoring": ["workflow", "implementation"],
+  "sdd.deprecate": ["workflow"],
+  "sdd.install_hooks": ["implementation"],
+  "sdd.brownfield_scan": ["analysis"],
+  "sdd.generate_cicd": ["implementation"],
+  "sdd.session_handoff": ["info"],
+  "sdd.migrate_storage": ["admin"],
+
+  // Info
+  "sdd.start_dashboard": ["admin"],
+  "sdd.mcp_server_info": ["info"],
+  "sdd.handle_mcp_tool": ["info"],
+}
+
+/**
+ * Mapeamento de tools composits para categorias de intenção.
+ */
+const COMPOSITE_CATEGORIES: Record<string, IntentCategory[]> = {
+  "sdd.graph_mutation": ["mutation"],
+  "sdd.graph_query": ["query"],
+  "sdd.traverse": ["query"],
+  "sdd.permissions": ["admin"],
+  "sdd.snapshot": ["admin"],
+  "sdd.sync": ["admin"],
+  "sdd.graph_admin": ["admin", "analysis"],
+  "sdd.code_quality": ["quality"],
+  "sdd.enterprise": ["enterprise"],
+  "sdd.drift_whitelist": ["analysis"],
+}
+
+/**
+ * Obtém as categorias de intenção para uma tool.
+ */
+export function getToolCategories(toolName: string): IntentCategory[] {
+  if (STANDALONE_CATEGORIES[toolName]) return STANDALONE_CATEGORIES[toolName]
+  if (COMPOSITE_CATEGORIES[toolName]) return COMPOSITE_CATEGORIES[toolName]
+  return ["info"] // fallback
+}
+
+/**
+ * Obtém todas as tools de uma categoria de intenção.
+ */
+export function getToolsByCategory(category: IntentCategory): string[] {
+  const tools: string[] = []
+
+  for (const [name, categories] of Object.entries(STANDALONE_CATEGORIES)) {
+    if (categories.includes(category)) tools.push(name)
+  }
+  for (const [name, categories] of Object.entries(COMPOSITE_CATEGORIES)) {
+    if (categories.includes(category)) tools.push(name)
+  }
+
+  return tools
+}
+
+/**
+ * Obtém categorias representadas em um conjunto de tools.
+ */
+export function getCategoriesInToolSet(toolNames: Set<string>): IntentCategory[] {
+  const categories = new Set<IntentCategory>()
+  for (const name of toolNames) {
+    for (const cat of getToolCategories(name)) {
+      categories.add(cat)
+    }
+  }
+  return [...categories]
+}
+
+/**
+ * Keywords associadas a cada categoria de intenção.
+ * Usado como sinal auxiliar no intent classifier.
+ */
+export const CATEGORY_KEYWORDS: Record<IntentCategory, string[]> = {
+  mutation: [
+    "criar", "adicionar", "remover", "deletar", "modificar", "atualizar",
+    "create", "add", "remove", "delete", "modify", "update",
+  ],
+  query: [
+    "buscar", "consultar", "mostrar", "listar", "ver", "inspecionar",
+    "search", "query", "show", "list", "find", "inspect", "get",
+  ],
+  workflow: [
+    "aprovar", "rejeitar", "completar", "falhar", "mudar", "change",
+    "approve", "reject", "complete", "fail", "change", "enforce",
+  ],
+  analysis: [
+    "analisar", "validar", "verificar", "detectar", "drift", "impacto",
+    "analyze", "validate", "verify", "detect", "drift", "impact",
+  ],
+  quality: [
+    "qualidade", "métrica", "smell", "complexidade", "dependência",
+    "quality", "metric", "smell", "complexity", "dependency", "dead code",
+  ],
+  enterprise: [
+    "migration", "experimento", "flag", "tenant", "segurança", "compliance",
+    "security", "monitoring", "incident", "sla", "custo",
+  ],
+  admin: [
+    "permissão", "role", "audit", "sync", "snapshot", "rollback", "cache",
+    "permission", "role", "sync", "snapshot", "rollback",
+  ],
+  discovery: [
+    "briefing", "descobrir", "perguntar", "especificação", "requisito",
+    "discover", "briefing", "question", "specification", "requirement",
+  ],
+  implementation: [
+    "implementar", "gerar código", "code", "generate", "planejar",
+    "implement", "build", "write", "plan",
+  ],
+  info: [
+    "status", "histórico", "help", "informação", "info",
+    "status", "history", "help", "information", "info",
+  ],
+}

package/src/opencode/router/embeddings.ts

@@ -0,0 +1,149 @@
+/**
+ * Similaridade local entre input do usuário e tools SDD.
+ *
+ * O roteamento usa BM25 lexical; as funções de embedding permanecem apenas
+ * como compatibilidade para consumidores externos e migração futura.
+ *
+ * Consumido por: intent-classifier.ts, semantic-nudge.ts
+ * Dependências: nenhuma (módulo puro)
+ */
+
+/** Dimensão dos embeddings (compatível com sentence-transformers all-MiniLM-L6-v2) */
+const EMBEDDING_DIM = 384
+
+/**
+ * Gera um embedding determinístico a partir de uma string.
+ * Usa hash simples para criar um vetor pseudo-aleatório.
+ * Para produção, substituir por chamada a um modelo real.
+ */
+function hashToEmbedding(text: string): number[] {
+  const embedding: number[] = new Array(EMBEDDING_DIM)
+  const normalized = text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim()
+  const words = normalized.split(/\s+/).filter(w => w.length > 1)
+
+  // Inicializar com zeros
+  for (let i = 0; i < EMBEDDING_DIM; i++) {
+    embedding[i] = 0
+  }
+
+  // Adicionar contribuição de cada palavra
+  for (const word of words) {
+    let hash = 0
+    for (let i = 0; i < word.length; i++) {
+      hash = ((hash << 5) - hash + word.charCodeAt(i)) | 0
+    }
+
+    // Espalhar a contribuição da palavra pelo vetor
+    const seed = Math.abs(hash)
+    for (let i = 0; i < EMBEDDING_DIM; i++) {
+      const val = Math.sin(seed * (i + 1) * 0.001) * 0.1
+      embedding[i] += val
+    }
+  }
+
+  // Normalizar
+  let norm = 0
+  for (let i = 0; i < EMBEDDING_DIM; i++) {
+    norm += embedding[i] * embedding[i]
+  }
+  norm = Math.sqrt(norm)
+  if (norm > 0) {
+    for (let i = 0; i < EMBEDDING_DIM; i++) {
+      embedding[i] /= norm
+    }
+  }
+
+  return embedding
+}
+
+/**
+ * Calcula similaridade coseno entre dois vetores.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) return 0
+  let dotProduct = 0
+  let normA = 0
+  let normB = 0
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i]
+    normA += a[i] * a[i]
+    normB += b[i] * b[i]
+  }
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB)
+  return denominator === 0 ? 0 : dotProduct / denominator
+}
+
+/**
+ * Cache de embeddings calculados.
+ */
+const embeddingCache = new Map<string, number[]>()
+
+/**
+ * Obtém o embedding para uma string (com cache).
+ */
+export function getEmbedding(text: string): number[] {
+  const cached = embeddingCache.get(text)
+  if (cached) return cached
+
+  const embedding = hashToEmbedding(text)
+  embeddingCache.set(text, embedding)
+  return embedding
+}
+
+/**
+ * Calcula similaridade entre um texto e múltiplas opções.
+ * Retorna pares (label, score) ordenados por similaridade decrescente.
+ */
+export function rankSimilarity(
+  query: string,
+  options: Array<{ label: string; text: string }>,
+): Array<{ label: string; score: number }> {
+  // Tool routing needs dependable lexical relevance, not an untrained hash
+  // vector that merely looks semantic. BM25 is local, deterministic and
+  // preserves exact technical terms, filenames and command names.
+  const tokenize = (text: string) => text.toLowerCase()
+    .normalize("NFD").replace(/[\u0300-\u036f]/g, "")
+    .split(/[^a-z0-9_./-]+/).filter((term) => term.length > 1)
+  const terms = tokenize(query)
+  const documents = options.map((option) => tokenize(option.text))
+  const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / Math.max(documents.length, 1)
+  const documentFrequency = new Map<string, number>()
+  for (const document of documents) {
+    for (const term of new Set(document)) documentFrequency.set(term, (documentFrequency.get(term) || 0) + 1)
+  }
+  return options.map((option, index) => {
+    const document = documents[index]
+    const frequencies = new Map<string, number>()
+    for (const term of document) frequencies.set(term, (frequencies.get(term) || 0) + 1)
+    const score = [...new Set(terms)].reduce((total, term) => {
+      const frequency = frequencies.get(term) || 0
+      if (!frequency) return total
+      const idf = Math.log(1 + (options.length - (documentFrequency.get(term) || 0) + 0.5) / ((documentFrequency.get(term) || 0) + 0.5))
+      const k1 = 1.2
+      const b = 0.75
+      return total + idf * (frequency * (k1 + 1)) / (frequency + k1 * (1 - b + b * document.length / Math.max(averageLength, 1)))
+    }, 0)
+    return { label: option.label, score }
+  }).sort((a, b) => b.score - a.score)
+}
+
+/**
+ * Limpa o cache de embeddings.
+ */
+export function clearEmbeddingCache(): void {
+  embeddingCache.clear()
+}
+
+/**
+ * Gera embeddings para todas as tools e retorna o mapa.
+ * Útil para pré-computação e persistência.
+ */
+export function generateToolEmbeddings(
+  tools: Array<{ name: string; description: string }>,
+): Map<string, number[]> {
+  const map = new Map<string, number[]>()
+  for (const tool of tools) {
+    map.set(tool.name, getEmbedding(tool.description))
+  }
+  return map
+}

package/src/opencode/router/graph-state-snapshot.ts

@@ -0,0 +1,163 @@
+/**
+ * Graph State Snapshot — Captura o estado do grafo para decisão de visibilidade de tools.
+ *
+ * Cache por sessão com TTL de 30s para evitar reads redundantes do disco.
+ *
+ * Consumido por: state-gate.ts, hooks.ts
+ */
+
+import { createRepository } from "../../sdd/persistence/repository.js"
+import type { KnowledgeGraph } from "../../sdd/domain/types.js"
+
+export type GraphState =
+  | "uninitialized"
+  | "empty"
+  | "partial"
+  | "ready"
+  | "has_change"
+  | "has_approved_change"
+  | "emergency"
+
+export interface GraphSnapshot {
+  state: GraphState
+  nodeCount: number
+  relationshipCount: number
+  nodeTypes: string[]
+  hasSpecNodes: boolean
+  hasChanges: boolean
+  pendingChangeCount: number
+  approvedChangeCount: number
+  hasWorkflow: boolean
+  /** Timestamp do snapshot (para TTL cache) */
+  timestamp: number
+}
+
+const CACHE_TTL_MS = 30_000 // 30 segundos
+
+const SPEC_NODE_TYPES = ["feature", "entity", "requirement", "architecture_component", "module"]
+
+let cachedSnapshot: GraphSnapshot | null = null
+let cachedDirectory: string | null = null
+
+/**
+ * Captura o estado atual do grafo (com cache).
+ * Se o cache ainda é válido (TTL < 30s), retorna o cache.
+ */
+export function getGraphSnapshot(directory: string): GraphSnapshot {
+  const now = Date.now()
+  if (cachedSnapshot && cachedDirectory === directory && (now - cachedSnapshot.timestamp) < CACHE_TTL_MS) {
+    return cachedSnapshot
+  }
+
+  const snapshot = captureSnapshot(directory)
+  cachedSnapshot = snapshot
+  cachedDirectory = directory
+  return snapshot
+}
+
+/**
+ * Força refresh do cache (após mutações no grafo).
+ */
+export function invalidateSnapshotCache(): void {
+  cachedSnapshot = null
+  cachedDirectory = null
+}
+
+function captureSnapshot(directory: string): GraphSnapshot {
+  const now = Date.now()
+
+  try {
+    const repo = createRepository(directory)
+    if (!repo.isInitialized()) {
+      return {
+        state: "uninitialized",
+        nodeCount: 0, relationshipCount: 0, nodeTypes: [],
+        hasSpecNodes: false, hasChanges: false,
+        pendingChangeCount: 0, approvedChangeCount: 0,
+        hasWorkflow: false, timestamp: now,
+      }
+    }
+
+    const graph = repo.loadGraph()
+    const nodeTypes = [...new Set(graph.nodes.map(n => n.type))]
+    const hasSpecNodes = graph.nodes.some(n => SPEC_NODE_TYPES.includes(n.type))
+    const changes = graph.nodes.filter(n => n.type === "change")
+    const pendingChanges = changes.filter(c => ["DRAFT", "PROPOSED"].includes(c.status))
+    const approvedChanges = changes.filter(c => c.status === "APPROVED")
+
+    // Detectar emergência (hotfix)
+    const hasEmergency = changes.some(c =>
+      c.name.toLowerCase().includes("hotfix") ||
+      c.name.toLowerCase().includes("emergency") ||
+      (c.metadata as Record<string, unknown>)?.approval_level === "POST_HOC"
+    )
+
+    // Detectar workflow ativo
+    let hasWorkflow = false
+    try {
+      const { getWorkflowState } = require("../../sdd/enforcement/workflow-tracker.js")
+      const wfState = getWorkflowState()
+      hasWorkflow = wfState.enforced === true
+    } catch {}
+
+    // Determinar estado
+    let state: GraphState
+    if (hasEmergency) {
+      state = "emergency"
+    } else if (approvedChanges.length > 0) {
+      state = "has_approved_change"
+    } else if (pendingChanges.length > 0) {
+      state = "has_change"
+    } else if (graph.nodes.length <= 1) {
+      state = "empty"
+    } else if (!hasSpecNodes) {
+      state = "partial"
+    } else {
+      state = "ready"
+    }
+
+    return {
+      state,
+      nodeCount: graph.nodes.length,
+      relationshipCount: graph.relationships.length,
+      nodeTypes,
+      hasSpecNodes,
+      hasChanges: changes.length > 0,
+      pendingChangeCount: pendingChanges.length,
+      approvedChangeCount: approvedChanges.length,
+      hasWorkflow,
+      timestamp: now,
+    }
+  } catch {
+    return {
+      state: "uninitialized",
+      nodeCount: 0, relationshipCount: 0, nodeTypes: [],
+      hasSpecNodes: false, hasChanges: false,
+      pendingChangeCount: 0, approvedChangeCount: 0,
+      hasWorkflow: false, timestamp: now,
+    }
+  }
+}
+
+/**
+ * Descrição legível do estado para debugging.
+ */
+export function formatGraphState(snapshot: GraphSnapshot): string {
+  const stateLabels: Record<GraphState, string> = {
+    uninitialized: "❌ Não inicializado",
+    empty: "📭 Grafo vazio",
+    partial: "⚠️ Parcial (sem spec nodes)",
+    ready: "✅ Pronto",
+    has_change: "📝 Com changes pendentes",
+    has_approved_change: "🟢 Com change aprovada",
+    emergency: "🚨 Emergência (hotfix)",
+  }
+
+  return [
+    `Estado: ${stateLabels[snapshot.state]}`,
+    `Nós: ${snapshot.nodeCount} | Relações: ${snapshot.relationshipCount}`,
+    `Spec nodes: ${snapshot.hasSpecNodes ? "sim" : "não"}`,
+    `Changes: ${snapshot.pendingChangeCount} pendente(s), ${snapshot.approvedChangeCount} aprovada(s)`,
+    `Workflow: ${snapshot.hasWorkflow ? "ativo" : "inativo"}`,
+  ].join("\n")
+}

package/src/opencode/router/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Router Module — Barrel export.
+ *
+ * Exporta todas as funções públicas do módulo router.
+ * Consumido por: hooks.ts
+ */
+
+// State Gate
+export { getVisibleTools, formatVisibleTools, ESCAPE_HATCH_INSTRUCTION } from "./state-gate.js"
+
+// Graph State Snapshot
+export { getGraphSnapshot, invalidateSnapshotCache, formatGraphState } from "./graph-state-snapshot.js"
+export type { GraphSnapshot, GraphState } from "./graph-state-snapshot.js"
+
+// Intent Classifier
+export { classifyIntent, getToolsForIntent } from "./intent-classifier.js"
+export type { IntentResult } from "./intent-classifier.js"
+
+// Tool Registry
+export { getToolsForSession, getToolDescription, listAllTools } from "./tool-registry.js"
+export type { ToolRegistryResult } from "./tool-registry.js"
+
+// Semantic Nudge
+export { calculateSemanticNudge, formatNudgeInput, isToolSuggested, getTopSuggestion } from "./semantic-nudge.js"
+export type { NudgeResult } from "./semantic-nudge.js"
+
+// Embeddings
+export { cosineSimilarity, getEmbedding, rankSimilarity } from "./embeddings.js"
+
+// Categories
+export { getToolCategories, getToolsByCategory, getCategoriesInToolSet, CATEGORY_KEYWORDS } from "./categories.js"
+export type { IntentCategory } from "./categories.js"
+
+// Tool Taxonomy
+export {
+  TOOL_TAXONOMY,
+  STANDALONE_TOOLS,
+  DEPRECATED_TOOLS,
+  TOOL_TO_COMPOSITE,
+  isDeprecatedTool,
+  getCompositeForTool,
+  countActiveTools,
+} from "./tool-taxonomy.js"
+export type { CompositeTool, SubAction, ToolCategory } from "./tool-taxonomy.js"

package/src/opencode/router/intent-classifier.ts

@@ -0,0 +1,140 @@
+/**
+ * Intent Classifier — Classifica a intenção do usuário a partir do input.
+ *
+ * Combina similaridade semântica (embeddings) com keywords para classificar
+ * a intenção em uma das categorias: mutation, query, workflow, analysis, etc.
+ *
+ * Consumido por: hooks.ts (experimental.chat.system.transform)
+ * Dependências: embeddings.ts, categories.ts
+ */
+
+import { rankSimilarity } from "./embeddings.js"
+import {
+  CATEGORY_KEYWORDS,
+  getToolsByCategory,
+  type IntentCategory,
+} from "./categories.js"
+import { TOOL_TAXONOMY, STANDALONE_TOOLS } from "./tool-taxonomy.js"
+
+export interface IntentResult {
+  category: IntentCategory
+  confidence: number
+  /** Top-3 categorias com scores */
+  topCategories: Array<{ category: IntentCategory; score: number }>
+}
+
+/**
+ * Embeddings pré-computados para descrições de categorias.
+ * Cada categoria tem uma descrição representativa.
+ */
+const CATEGORY_DESCRIPTIONS: Record<IntentCategory, string> = {
+  mutation: "Create, add, update, or remove nodes and relationships in the knowledge graph",
+  query: "Search, query, list, inspect, or retrieve information from the knowledge graph",
+  workflow: "Manage changes, approvals, enforcement, lifecycle of specifications",
+  analysis: "Analyze impact, validate, detect drift, check integrity of the specification",
+  quality: "Code quality metrics, complexity, smells, dependencies, dead code detection",
+  enterprise: "Enterprise workflows: migrations, experiments, feature flags, security, compliance",
+  admin: "Administration: permissions, roles, sync, snapshots, cache, configuration",
+  discovery: "Discover requirements, analyze briefings, ask questions, elicit specifications",
+  implementation: "Generate code, plan implementation, create files from specification",
+  info: "Get status, history, help, general information about the project",
+}
+
+/**
+ * Calcula score de keywords para cada categoria.
+ */
+function keywordScore(text: string): Record<IntentCategory, number> {
+  const normalized = text.toLowerCase()
+  const scores: Record<IntentCategory, number> = {} as any
+
+  for (const [category, keywords] of Object.entries(CATEGORY_KEYWORDS) as [IntentCategory, string[]][]) {
+    let score = 0
+    for (const keyword of keywords) {
+      if (normalized.includes(keyword.toLowerCase())) {
+        score += 1
+      }
+    }
+    scores[category] = score
+  }
+
+  return scores
+}
+
+/**
+ * Calcula score de embeddings para cada categoria.
+ */
+function embeddingScore(text: string): Record<IntentCategory, number> {
+  const options = Object.entries(CATEGORY_DESCRIPTIONS).map(([category, description]) => ({
+    label: category,
+    text: description,
+  }))
+
+  const ranked = rankSimilarity(text, options)
+
+  const scores: Record<IntentCategory, number> = {} as any
+  for (const r of ranked) {
+    scores[r.label as IntentCategory] = r.score
+  }
+
+  return scores
+}
+
+/**
+ * Combina keyword score e embedding score com pesos.
+ * Keywords: 0.4, Embeddings: 0.6
+ */
+function combinedScore(text: string): Record<IntentCategory, number> {
+  const kw = keywordScore(text)
+  const emb = embeddingScore(text)
+
+  const combined: Record<IntentCategory, number> = {} as any
+  for (const category of Object.keys(kw) as IntentCategory[]) {
+    combined[category] = (kw[category] * 0.4) + ((emb[category] || 0) * 0.6)
+  }
+
+  return combined
+}
+
+/**
+ * Classifica a intenção do usuário.
+ *
+ * @param text - Input do usuário
+ * @returns IntentResult com categoria, confidence e top-3
+ */
+export function classifyIntent(text: string): IntentResult {
+  const scores = combinedScore(text)
+
+  // Ordenar por score decrescente
+  const sorted = Object.entries(scores)
+    .map(([category, score]) => ({ category: category as IntentCategory, score }))
+    .sort((a, b) => b.score - a.score)
+
+  const top = sorted[0]
+  const totalScore = sorted.reduce((sum, s) => sum + Math.max(0, s.score), 0)
+  const confidence = totalScore > 0 ? top.score / totalScore : 0
+
+  return {
+    category: top.category,
+    confidence: Math.min(1, Math.max(0, confidence)),
+    topCategories: sorted.slice(0, 3),
+  }
+}
+
+/**
+ * Obtém as tools relevantes para uma intenção, combinando com o state gate.
+ *
+ * @param intent - Resultado da classificação
+ * @param stateTools - Tools visíveis pelo state gate (null = todas)
+ * @returns Lista de tools relevantes
+ */
+export function getToolsForIntent(
+  intent: IntentResult,
+  stateTools: Set<string> | null,
+): string[] {
+  const categoryTools = getToolsByCategory(intent.category)
+
+  if (!stateTools) return categoryTools
+
+  // Interseção: tools da categoria ∩ tools visíveis pelo estado
+  return categoryTools.filter(t => stateTools.has(t))
+}