opencode-telos 1.0.0

package/src/opencode/router/semantic-nudge.ts

@@ -0,0 +1,89 @@
+/**
+ * Semantic Nudge — Sugestões locais por relevância lexical determinística.
+ *
+ * Calcula relevância BM25 entre o input do usuário e as tool descriptions.
+ * Injeta hints no input do LLM com as tools mais relevantes.
+ *
+ * Consumido por: hooks.ts (chat.message hook)
+ * Dependências: embeddings.ts, tool-embeddings.ts, categories.ts
+ */
+
+import { rankSimilarity } from "./embeddings.js"
+import { getCachedToolEmbeddings } from "./tool-embeddings.js"
+
+export interface NudgeResult {
+  /** Hints formatados para injetar no input */
+  hints: string[]
+  /** Tools sugeridas com confidence */
+  suggestions: Array<{ tool: string; confidence: number }>
+}
+
+/** Minimum lexical relevance for a suggestion. BM25 scores are unbounded. */
+const CONFIDENCE_THRESHOLD = 0.35
+
+/** Máximo de sugestões */
+const MAX_SUGGESTIONS = 3
+
+/**
+ * Calcula nudges semânticos para o input do usuário.
+ *
+ * @param userInput - Texto do input do usuário
+ * @returns NudgeResult com hints e sugestões
+ */
+export function calculateSemanticNudge(userInput: string): NudgeResult {
+  const toolEmbeddings = getCachedToolEmbeddings()
+  const topLevelTools = toolEmbeddings.filter((tool) => !tool.name.includes(":"))
+  const ranked = rankSimilarity(userInput, topLevelTools.map((tool) => ({
+    label: tool.name,
+    text: `${tool.name} ${tool.description}`,
+  })))
+  const byName = new Map(topLevelTools.map((tool) => [tool.name, tool]))
+  const scores = ranked
+    .filter((item) => item.score >= CONFIDENCE_THRESHOLD)
+    .map((item) => ({ tool: byName.get(item.label)!, score: item.score }))
+
+  // Ordenar por score e pegar top-N
+  scores.sort((a, b) => b.score - a.score)
+  const topScores = scores.slice(0, MAX_SUGGESTIONS)
+
+  // Gerar hints
+  const hints: string[] = []
+  const suggestions: Array<{ tool: string; confidence: number }> = []
+
+  if (topScores.length > 0) {
+    hints.push("[SDD Tools Sugeridas]")
+    for (const { tool, score } of topScores) {
+      const confidencePct = Math.round(score * 100)
+      hints.push(`- ${tool.name} (${confidencePct}%): ${tool.description}`)
+      suggestions.push({ tool: tool.name, confidence: score })
+    }
+  }
+
+  return { hints, suggestions }
+}
+
+/**
+ * Gera a string de nudge para injetar no input do LLM.
+ * Retorna string vazia se não houver nudges relevantes.
+ */
+export function formatNudgeInput(userInput: string): string {
+  const result = calculateSemanticNudge(userInput)
+  if (result.hints.length === 0) return ""
+  return result.hints.join("\n")
+}
+
+/**
+ * Verifica se uma tool específica é sugerida pelo nudge.
+ */
+export function isToolSuggested(userInput: string, toolName: string): boolean {
+  const result = calculateSemanticNudge(userInput)
+  return result.suggestions.some(s => s.tool === toolName)
+}
+
+/**
+ * Obtém a tool mais sugerida para o input.
+ */
+export function getTopSuggestion(userInput: string): { tool: string; confidence: number } | null {
+  const result = calculateSemanticNudge(userInput)
+  return result.suggestions[0] || null
+}

package/src/opencode/router/state-gate.ts

@@ -0,0 +1,192 @@
+/**
+ * State Gate — Determina quais tools são visíveis para cada estado do grafo.
+ *
+ * Reduz o espaço de escolha do LLM mostrando apenas tools relevantes.
+ * Fallback: se o resultado for vazio, mostra todas as tools.
+ *
+ * Consumido por: hooks.ts (experimental.chat.system.transform)
+ * Dependências: graph-state-snapshot.ts, tool-taxonomy.ts
+ */
+
+import { getGraphSnapshot, type GraphState, type GraphSnapshot } from "./graph-state-snapshot.js"
+import { STANDALONE_TOOLS, TOOL_TAXONOMY, type ToolCategory } from "./tool-taxonomy.js"
+
+/** Tools que são sempre visíveis (essenciais) */
+const ALWAYS_VISIBLE = new Set([
+  "sdd.inspect",
+  "sdd.query_graph",
+  "sdd.validate",
+  "sdd.detect_drift",
+  "sdd.get_context",
+])
+
+/** Tools de composits que são sempre visíveis */
+const ALWAYS_VISIBLE_COMPOSITES = new Set([
+  "sdd.graph_query",
+  "sdd.graph_mutation",
+  "sdd.traverse",
+])
+
+/**
+ * Mapeamento de estado → tools composits visíveis.
+ * Keys são subconjuntos de GraphState.
+ */
+const STATE_TOOLS: Record<GraphState, { composite: string[]; standalone: string[] }> = {
+  uninitialized: {
+    composite: [],
+    standalone: ["sdd.initialize", "sdd.build_graph", "sdd.discover"],
+  },
+  empty: {
+    composite: ["sdd.graph_mutation"],
+    standalone: ["sdd.build_graph", "sdd.discover", "sdd.inspect"],
+  },
+  partial: {
+    composite: ["sdd.graph_mutation", "sdd.graph_query"],
+    standalone: [
+      "sdd.discover", "sdd.update_from_answers", "sdd.inspect",
+      "sdd.build_graph", "sdd.enforce",
+    ],
+  },
+  ready: {
+    composite: [
+      "sdd.graph_mutation", "sdd.graph_query", "sdd.traverse",
+      "sdd.code_quality", "sdd.graph_admin",
+    ],
+    standalone: [
+      "sdd.enforce", "sdd.build_graph", "sdd.discover",
+      "sdd.pending_changes", "sdd.change_history",
+    ],
+  },
+  has_change: {
+    composite: [
+      "sdd.graph_mutation", "sdd.graph_query", "sdd.traverse",
+      "sdd.code_quality", "sdd.graph_admin", "sdd.permissions",
+    ],
+    standalone: [
+      "sdd.enforce", "sdd.approve_change", "sdd.update_from_answers",
+      "sdd.pending_changes", "sdd.change_history", "sdd.impact_report",
+    ],
+  },
+  has_approved_change: {
+    composite: [
+      "sdd.graph_mutation", "sdd.graph_query", "sdd.traverse",
+      "sdd.code_quality", "sdd.graph_admin", "sdd.permissions",
+      "sdd.snapshot", "sdd.sync",
+    ],
+    standalone: [
+      "sdd.generate_code", "sdd.complete_change", "sdd.fail_change",
+      "sdd.validate", "sdd.detect_drift",
+    ],
+  },
+  emergency: {
+    composite: [
+      "sdd.graph_mutation", "sdd.graph_query", "sdd.traverse",
+      "sdd.snapshot",
+    ],
+    standalone: [
+      "sdd.hotfix", "sdd.validate", "sdd.complete_change",
+    ],
+  },
+}
+
+/**
+ * Categorias de tools que ficam ocultas em certos estados.
+ */
+const CATEGORY_HIDDEN: Record<GraphState, ToolCategory[]> = {
+  uninitialized: ["quality", "sync", "enterprise", "admin"],
+  empty: ["quality", "sync", "enterprise"],
+  partial: ["sync", "enterprise"],
+  ready: ["sync"],
+  has_change: [],
+  has_approved_change: [],
+  emergency: ["quality", "sync", "enterprise"],
+}
+
+/**
+ * Obtém as tools visíveis para o estado atual do grafo.
+ *
+ * @param directory - Diretório do projeto
+ * @returns Set de nomes de tools visíveis. Se vazio (fallback), retorna null para indicar "todas".
+ */
+export function getVisibleTools(directory: string): Set<string> | null {
+  const snapshot = getGraphSnapshot(directory)
+  const stateConfig = STATE_TOOLS[snapshot.state]
+  const hiddenCategories = CATEGORY_HIDDEN[snapshot.state] || []
+
+  const visible = new Set<string>()
+
+  // Adicionar sempre-visíveis
+  for (const t of ALWAYS_VISIBLE) visible.add(t)
+  for (const t of ALWAYS_VISIBLE_COMPOSITES) visible.add(t)
+
+  // Adicionar tools do estado
+  for (const t of stateConfig.standalone) visible.add(t)
+  for (const t of stateConfig.composite) visible.add(t)
+
+  // Adicionar composits de categories não-ocultas
+  for (const tool of TOOL_TAXONOMY) {
+    if (!hiddenCategories.includes(tool.category)) {
+      visible.add(tool.name)
+    }
+  }
+
+  // Se o resultado é muito pequeno (< 5 tools), retornar null (fallback: todas)
+  if (visible.size < 5) {
+    return null
+  }
+
+  return visible
+}
+
+/**
+ * Formata a lista de tools visíveis para injeção no system prompt.
+ */
+export function formatVisibleTools(visibleTools: Set<string> | null): string {
+  if (!visibleTools) {
+    return "[Todas as tools SDD disponíveis]"
+  }
+
+  const lines = ["## Tools SDD Disponíveis para Este Estado\n"]
+
+  // Agrupar por tipo
+  const standalone: string[] = []
+  const composite: string[] = []
+
+  for (const name of visibleTools) {
+    if (TOOL_TAXONOMY.find(t => t.name === name)) {
+      composite.push(name)
+    } else {
+      standalone.push(name)
+    }
+  }
+
+  if (standalone.length > 0) {
+    lines.push("### Tools Individuais")
+    for (const t of standalone.sort()) {
+      lines.push(`- \`${t}\``)
+    }
+  }
+
+  if (composite.length > 0) {
+    lines.push("\n### Tools Compositas (use action= para sub-comando)")
+    for (const t of composite.sort()) {
+      const tool = TOOL_TAXONOMY.find(tc => tc.name === t)
+      if (tool) {
+        const actions = tool.actions.map(a => a.name).join(", ")
+        lines.push(`- \`${t}\` → [${actions}]`)
+      }
+    }
+  }
+
+  return lines.join("\n")
+}
+
+/**
+ * Escape hatch: instrução para o LLM mostrar todas as tools se necessário.
+ */
+export const ESCAPE_HATCH_INSTRUCTION = `
+### Tools SDD Não Listadas?
+Se precisar de uma tool que não está na lista acima, você pode:
+1. Usar a tool original diretamente (todas ainda existem)
+2. Pedir ao usuário para usar \`/sdd status\` para ver todas as tools disponíveis
+`.trim()

package/src/opencode/router/tool-embeddings.ts

@@ -0,0 +1,162 @@
+/**
+ * Tool catalog — Descriptions cacheadas para todas as tools SDD.
+ *
+ * Mantém o catálogo usado pelo roteamento lexical. O campo embedding é
+ * preservado por compatibilidade com consumidores antigos.
+ *
+ * Consumido por: semantic-nudge.ts
+ * Dependências: embeddings.ts, tool-taxonomy.ts
+ */
+
+import { getEmbedding } from "./embeddings.js"
+import { TOOL_TAXONOMY, STANDALONE_TOOLS } from "./tool-taxonomy.js"
+
+export interface ToolEmbedding {
+  name: string
+  description: string
+  embedding: number[]
+  category: string
+}
+
+/**
+ * Descriptions das tools standalone (nomes → descriptions representativas).
+ * Em produção, extrair das ToolDefinitions reais.
+ */
+const STANDALONE_DESCRIPTIONS: Record<string, string> = {
+  "sdd.initialize": "Initialize the SDD Knowledge Graph for a project",
+  "sdd.inspect": "Inspect the current state of the SDD Knowledge Graph stats",
+  "sdd.query_graph": "Query the SDD Knowledge Graph search for nodes",
+  "sdd.analyze_impact": "Perform impact analysis for a change request traverse graph",
+  "sdd.create_change": "Create a Change node in the SDD Knowledge Graph",
+  "sdd.discover": "Analyze a user briefing and return discovery questions",
+  "sdd.update_from_answers": "Update the Knowledge Graph based on user answers",
+  "sdd.validate": "Validate the SDD Knowledge Graph for structural integrity",
+  "sdd.detect_drift": "Detect SDD drift discrepancies between specification and codebase",
+  "sdd.get_context": "Build a context pack for a specific node",
+  "sdd.approve_change": "Approve a pending change in the SDD graph",
+  "sdd.complete_change": "Mark a change as completed check pending promises",
+  "sdd.fail_change": "Mark a change as FAILED with a reason",
+  "sdd.change_history": "View the full history of all changes in the SDD graph",
+  "sdd.impact_report": "Generate a detailed impact report for a specific change",
+  "sdd.pending_changes": "List all pending changes in the SDD graph",
+  "sdd.generate_code": "Generate project code from the SDD Knowledge Graph",
+  "sdd.enforce": "Classify a change request and create a Change node",
+  "sdd.enforce_rules": "Show the current SDD enforcement rules",
+  "sdd.full_cycle": "Run the complete SDD workflow cycle from enforcement to completion",
+  "sdd.toggle": "Toggle SDD enforcement on or off",
+  "sdd.constitution": "Manage the project constitution principles",
+  "sdd.promises": "Manage promises and commitments in the SDD graph",
+  "sdd.quality": "Calculate quality score for the SDD graph",
+  "sdd.session_handoff": "Generate a session handoff pack for context continuity",
+  "sdd.anti_patterns": "Detect anti-patterns in the SDD graph",
+  "sdd.clone_detection": "Detect near-duplicate nodes and AST clones",
+  "sdd.contradictions": "Detect contradictions in the SDD graph",
+  "sdd.coverage": "Calculate test coverage for requirements",
+  "sdd.install_hooks": "Install git hooks for SDD enforcement",
+  "sdd.brownfield_scan": "Scan existing project and create SDD nodes for brownfield",
+  "sdd.generate_cicd": "Generate CI/CD pipeline configuration from SDD graph",
+  "sdd.bug_fix": "Automated bug fix workflow through SDD",
+  "sdd.hotfix": "Emergency hotfix workflow bypassing normal enforcement",
+  "sdd.refactoring": "Safe refactoring workflow with test validation",
+  "sdd.deprecate": "Deprecation workflow with migration guide",
+  "sdd.toggle_status": "Show current SDD toggle status",
+  "sdd.drift_signals": "Detect advanced drift signals mutant duplicates architecture violations",
+  "sdd.build_graph": "Build the entire Knowledge Graph from a project briefing",
+  "sdd.auto_link_tests": "Automatically link orphan tests to requirements",
+  "sdd.migrate_storage": "Migrate SDD storage between YAML and SQLite backends",
+  "sdd.start_dashboard": "Start the SDD dashboard server",
+  "sdd.mcp_server_info": "Show MCP server information and capabilities",
+  "sdd.handle_mcp_tool": "Handle an MCP tool call from an external client",
+}
+
+/**
+ * Gera embeddings para todas as tools (standalone + composite).
+ */
+export function generateAllToolEmbeddings(): ToolEmbedding[] {
+  const embeddings: ToolEmbedding[] = []
+
+  // Standalone tools
+  for (const name of STANDALONE_TOOLS) {
+    const description = STANDALONE_DESCRIPTIONS[name] || `SDD tool: ${name}`
+    embeddings.push({
+      name,
+      description,
+      embedding: getEmbedding(description),
+      category: "standalone",
+    })
+  }
+
+  // Composite tools
+  for (const tool of TOOL_TAXONOMY) {
+    embeddings.push({
+      name: tool.name,
+      description: tool.description,
+      embedding: getEmbedding(tool.description),
+      category: tool.category,
+    })
+
+    // Sub-actions também ganham embeddings
+    for (const action of tool.actions) {
+      embeddings.push({
+        name: `${tool.name}:${action.name}`,
+        description: `${action.description} (${tool.label})`,
+        embedding: getEmbedding(action.description),
+        category: tool.category,
+      })
+    }
+  }
+
+  return embeddings
+}
+
+/**
+ * Cache global de embeddings.
+ */
+let cachedEmbeddings: ToolEmbedding[] | null = null
+
+/**
+ * Obtém embeddings com cache.
+ */
+export function getCachedToolEmbeddings(): ToolEmbedding[] {
+  if (!cachedEmbeddings) {
+    cachedEmbeddings = generateAllToolEmbeddings()
+  }
+  return cachedEmbeddings
+}
+
+/**
+ * Força regeneração do cache.
+ */
+export function refreshToolEmbeddings(): ToolEmbedding[] {
+  cachedEmbeddings = generateAllToolEmbeddings()
+  return cachedEmbeddings
+}
+
+/**
+ * Serializa embeddings para JSON (para persistência).
+ */
+export function serializeEmbeddings(embeddings: ToolEmbedding[]): string {
+  return JSON.stringify(
+    embeddings.map(e => ({
+      n: e.name,
+      d: e.description,
+      e: e.embedding,
+      c: e.category,
+    })),
+    null,
+    2,
+  )
+}
+
+/**
+ * Desserializa embeddings de JSON.
+ */
+export function deserializeEmbeddings(json: string): ToolEmbedding[] {
+  const data = JSON.parse(json)
+  return data.map((e: any) => ({
+    name: e.n,
+    description: e.d,
+    embedding: e.e,
+    category: e.c,
+  }))
+}

package/src/opencode/router/tool-registry.ts

@@ -0,0 +1,135 @@
+/**
+ * Tool Registry — Registry central de tools SDD.
+ *
+ * Mantém a lista completa de tools, filtra por estado (state gate)
+ * e intenção (intent classifier), e fornece o conjunto final para o LLM.
+ *
+ * Consumido por: hooks.ts (experimental.chat.system.transform)
+ * Dependências: state-gate.ts, intent-classifier.ts, tool-taxonomy.ts
+ */
+
+import { getVisibleTools, formatVisibleTools, ESCAPE_HATCH_INSTRUCTION } from "./state-gate.js"
+import { classifyIntent, getToolsForIntent, type IntentResult } from "./intent-classifier.js"
+import { TOOL_TAXONOMY, STANDALONE_TOOLS, type CompositeTool } from "./tool-taxonomy.js"
+
+export interface ToolRegistryResult {
+  /** Tools finais selecionadas para o LLM */
+  tools: string[]
+  /** Resultado da classificação de intenção */
+  intent: IntentResult
+  /** Se null, todas as tools estão disponíveis (fallback) */
+  stateTools: Set<string> | null
+  /** Mensagem formatada para injeção no system prompt */
+  formattedMessage: string
+}
+
+/**
+ * Obtém o conjunto final de tools para o LLM.
+ *
+ * Combina state gate (tools visíveis pelo estado do grafo)
+ * com intent classifier (tools relevantes para a intenção).
+ *
+ * @param directory - Diretório do projeto
+ * @param userInput - Texto do input do usuário
+ * @returns ToolRegistryResult com tools selecionadas e mensagem formatada
+ */
+export function getToolsForSession(directory: string, userInput: string): ToolRegistryResult {
+  // 1. State gate: quais tools são visíveis pelo estado do grafo?
+  const stateTools = getVisibleTools(directory)
+
+  // 2. Intent classifier: qual a intenção do usuário?
+  const intent = classifyIntent(userInput)
+
+  // 3. Interseção: tools da intenção ∩ tools visíveis
+  const tools = getToolsForIntent(intent, stateTools)
+
+  // 4. Se resultado muito pequeno, usar fallback (todas as tools do estado)
+  const finalTools = tools.length >= 3 ? tools : (stateTools ? [...stateTools] : [...STANDALONE_TOOLS, ...TOOL_TAXONOMY.map(t => t.name)])
+
+  // 5. Formatar mensagem para o system prompt
+  const formattedMessage = formatToolRegistryMessage(finalTools, intent, stateTools)
+
+  return {
+    tools: finalTools,
+    intent,
+    stateTools,
+    formattedMessage,
+  }
+}
+
+/**
+ * Formata a mensagem do tool registry para o system prompt.
+ */
+function formatToolRegistryMessage(
+  tools: string[],
+  intent: IntentResult,
+  stateTools: Set<string> | null,
+): string {
+  const lines: string[] = []
+
+  // Header com intenção detectada
+  const confidencePct = Math.round(intent.confidence * 100)
+  lines.push(`## Intent Detectado: ${intent.category} (${confidencePct}% confiança)`)
+  if (intent.topCategories.length > 1) {
+    const alternatives = intent.topCategories.slice(1).map(c => `${c.category} (${Math.round(c.score * 100)}%)`).join(", ")
+    lines.push(`Alternativas: ${alternatives}`)
+  }
+  lines.push("")
+
+  // Tools selecionadas
+  const standalone = tools.filter(t => STANDALONE_TOOLS.includes(t))
+  const composite = tools.filter(t => TOOL_TAXONOMY.find(tc => tc.name === t))
+
+  if (standalone.length > 0) {
+    lines.push("### Tools Individuais")
+    for (const t of standalone.sort()) {
+      lines.push(`- \`${t}\``)
+    }
+  }
+
+  if (composite.length > 0) {
+    lines.push("\n### Tools Compositas (use action= para sub-comando)")
+    for (const t of composite.sort()) {
+      const tool = TOOL_TAXONOMY.find(tc => tc.name === t)
+      if (tool) {
+        const actions = tool.actions.map(a => a.name).join(", ")
+        lines.push(`- \`${t}\` → [${actions}]`)
+      }
+    }
+  }
+
+  // Escape hatch
+  lines.push("")
+  lines.push(ESCAPE_HATCH_INSTRUCTION)
+
+  return lines.join("\n")
+}
+
+/**
+ * Obtém descrição de uma tool (standalone ou composite).
+ */
+export function getToolDescription(toolName: string): string {
+  // Tentar standalone primeiro
+  if (STANDALONE_TOOLS.includes(toolName)) {
+    return `SDD tool: ${toolName}`
+  }
+
+  // Tentar composite
+  const composite = TOOL_TAXONOMY.find(t => t.name === toolName)
+  if (composite) {
+    return composite.description
+  }
+
+  return `Unknown tool: ${toolName}`
+}
+
+/**
+ * Lista todas as tools ativas (composits + standalone) com contagem.
+ */
+export function listAllTools(): { standalone: string[]; composite: CompositeTool[]; total: number } {
+  return {
+    standalone: STANDALONE_TOOLS,
+    composite: TOOL_TAXONOMY,
+    total: STANDALONE_TOOLS.length + TOOL_TAXONOMY.length,
+  }
+}