altis-claude-harness 1.0.2 → 1.2.0

package/bin/cli.js

@@ -6,6 +6,7 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { readManifest, writeManifest, MANIFEST_NAME, hashFile } = require('../lib/manifest');
 const { mergeSettings, removeAltisEntries } = require('../lib/settings');
+const { mcpConfigPath, mergeMcpConfig, removeMcpConfig } = require('../lib/mcp');
 const { syncPayload } = require('../lib/sync');
 const { getLatestVersion, PKG_NAME } = require('../lib/remote');
 const license = require('../payload/hooks/license_guard.cjs');
@@ -27,6 +28,10 @@ function loadFragment() {
   return JSON.parse(fs.readFileSync(path.join(PAYLOAD_DIR, 'settings-fragment.json'), 'utf8'));
 }
 
+function loadMcpFragment() {
+  return JSON.parse(fs.readFileSync(path.join(PAYLOAD_DIR, 'mcp-fragment.json'), 'utf8'));
+}
+
 function checkPython() {
   for (const bin of ['python', 'python3', 'py']) {
     try {
@@ -50,6 +55,7 @@ function runSync(target) {
   const old = readManifest(target);
   const result = syncPayload(PAYLOAD_DIR, target, (old && old.files) || {});
   mergeSettings(path.join(target, 'settings.json'), loadFragment());
+  mergeMcpConfig(mcpConfigPath(target), loadMcpFragment());
   const now = new Date().toISOString();
   const manifest = {
     version: PKG.version,
@@ -85,6 +91,7 @@ function cmdInstall(target) {
   console.log(`${PKG_NAME} v${PKG.version} instalado em ${target}`);
   console.log(`  ${Object.keys(result.files).length} arquivos gerenciados (agents, commands, rules, skills, hooks)`);
   console.log('  settings.json atualizado (hooks Altis + licenca + auto-update por sessao)');
+  console.log('  MCP altis-rag configurado (base de conhecimento RAG - sem configuracao manual)');
   for (const w of result.warnings) console.log(`  aviso: ${w}`);
   if (!checkPython()) {
     console.log('  aviso: Python nao encontrado no PATH - os hooks Delphi nao vao funcionar.');
@@ -135,6 +142,7 @@ function cmdUninstall(target) {
   }
   try { fs.rmSync(path.join(target, 'hooks', 'altis'), { recursive: true, force: true }); } catch {}
   removeAltisEntries(path.join(target, 'settings.json'));
+  try { removeMcpConfig(mcpConfigPath(target), loadMcpFragment()); } catch {}
   try { fs.unlinkSync(path.join(target, MANIFEST_NAME)); } catch {}
   console.log(`${PKG_NAME} removido de ${target} (backup do settings preservado)`);
 }

package/lib/mcp.js

@@ -0,0 +1,65 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+function mcpConfigPath(target) {
+  return path.join(path.dirname(target), path.basename(target) + '.json');
+}
+
+function readConfig(configPath) {
+  if (!fs.existsSync(configPath)) return {};
+  const raw = fs.readFileSync(configPath, 'utf8');
+  if (raw.trim() === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`config invalido (${configPath}): corrija o JSON antes de continuar. Detalhe: ${e.message}`);
+  }
+}
+
+function backupOnce(configPath) {
+  const bak = configPath + '.altis-bak';
+  if (fs.existsSync(configPath) && !fs.existsSync(bak)) {
+    fs.copyFileSync(configPath, bak);
+    return true;
+  }
+  return false;
+}
+
+function writeConfig(configPath, config) {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+function mergeMcpConfig(configPath, fragment) {
+  const servers = (fragment && fragment.mcpServers) || {};
+  const config = readConfig(configPath);
+  const atual = config.mcpServers || {};
+  let changed = false;
+  for (const [nome, def] of Object.entries(servers)) {
+    if (JSON.stringify(atual[nome]) !== JSON.stringify(def)) changed = true;
+  }
+  if (!changed) return { changed: false, backedUp: false };
+  const backedUp = backupOnce(configPath);
+  config.mcpServers = { ...atual, ...servers };
+  writeConfig(configPath, config);
+  return { changed: true, backedUp };
+}
+
+function removeMcpConfig(configPath, fragment) {
+  if (!fs.existsSync(configPath)) return { changed: false };
+  const config = readConfig(configPath);
+  if (!config.mcpServers) return { changed: false };
+  let changed = false;
+  for (const nome of Object.keys((fragment && fragment.mcpServers) || {})) {
+    if (nome in config.mcpServers) {
+      delete config.mcpServers[nome];
+      changed = true;
+    }
+  }
+  if (Object.keys(config.mcpServers).length === 0) delete config.mcpServers;
+  if (changed) writeConfig(configPath, config);
+  return { changed };
+}
+
+module.exports = { mcpConfigPath, mergeMcpConfig, removeMcpConfig, readConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altis-claude-harness",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Padroes Claude Code da Altis Sistemas - instalador, auto-update e liberacao por estacao",
   "bin": {
     "altis-claude-harness": "bin/cli.js"

package/payload/commands/altis-bugfix.md

@@ -152,6 +152,16 @@ Classifique o bug em um dos níveis abaixo (a classificação é registrada no S
 
 ---
 
+## Passo 1.7 — Consulta à base de conhecimento (RAG)
+
+Antes de diagnosticar, consulte a memória da equipe: chame a ferramenta MCP `buscar_conhecimento` (servidor `altis-rag`) com o sintoma/mensagem de erro como `consulta`, priorizando `tipos=["BUG"]` (limite 5); se necessário, repita sem filtro de tipo.
+
+- Um `BUG` similar já corrigido → aproveite a causa raiz e a solução registradas como hipótese inicial do diagnóstico (valide no código atual antes de assumir).
+- Registros `REG`/`DEC` relacionados → o "bug" pode ser comportamento intencional; leve essa hipótese ao pre-flight de negócio do Passo 2.5.
+- Servidor indisponível → avise o usuário e **continue normalmente** — nunca bloqueie o bugfix por causa do RAG.
+
+---
+
 ## Passo 2 — Diagnóstico e identificação da causa raiz
 
 Antes de propor qualquer fix, **entenda o bug profundamente**. Esta fase é crucial — um fix sem diagnóstico correto gera regressão.
@@ -621,6 +631,16 @@ Se o bug envolve **SEFAZ, SiTef, WhatsApp, Banco Inter, OpenAI, Discord, RedeCon
 1. **PLAN.md** — preencher `## Resultado final` e `## RCA`, alterar `**Status:**` para `concluído`.
 2. **SPEC.md** — alterar `**Status:**` para `concluído`.
 
+### Gravação na base de conhecimento (RAG)
+
+Após fechar o RCA, grave o aprendizado na base compartilhada via ferramenta MCP `gravar_conhecimento` (servidor `altis-rag`), conforme a rule `altis-rag-rule.md`:
+
+1. **Sempre** um registro `BUG`: título = sintoma pesquisável; conteúdo = causa raiz + solução aplicada + prevenção futura (fonte: seção RCA do PLAN.md), ≤ 2.000 chars. `origem='AUT'`, `projeto` = camada principal do fix, `arquivos` = arquivos corrigidos, `ticket` se houver.
+2. Um registro `REG` se o diagnóstico revelou **regra de negócio não documentada**.
+3. Metadados: `autor` = `git config user.name`; `hostname_usuario` = `$env:COMPUTERNAME`; `modelo_llm` = model id da sessão.
+4. Se retornar `gravado=false` com `similares` (bug recorrente), atualize o registro existente com a nova ocorrência via `atualizar_conhecimento` em vez de duplicar.
+5. Falha/indisponibilidade → exiba o conteúdo estruturado no chat para regravação via `/altis-rag`; não trave o relatório.
+
 ### Resumo ao usuário
 
 Entregue um resumo conciso:

package/payload/commands/altis-feature.md

@@ -89,6 +89,16 @@ Se o argumento estiver vazio ou ambíguo, **pergunte ao usuário** qual feature
 
 ---
 
+## Passo 0.7 — Consulta à base de conhecimento (RAG)
+
+Antes de decompor, consulte a memória da equipe: chame a ferramenta MCP `buscar_conhecimento` (servidor `altis-rag`) com a descrição da feature como `consulta` (limite 5). Considere também uma segunda busca com termos alternativos se a primeira não retornar nada útil.
+
+- Registros `FEA`/`DEC` similares → a feature (ou parte dela) pode já ter sido implementada ou decidida — trate como insumo do Passo 1 e repasse aos pre-flights do Passo 1.5 nos briefings.
+- Registros `REG` relevantes → regras de negócio a respeitar; inclua nos briefings dos workers.
+- Servidor indisponível → avise o usuário ("base de conhecimento fora do ar, seguindo sem memória") e **continue normalmente** — nunca bloqueie a feature por causa do RAG.
+
+---
+
 ## Passo 1 — Decomposição da feature
 
 Analise a descrição e identifique **quais camadas do sistema serão tocadas**. Responda mentalmente:
@@ -523,6 +533,17 @@ Antes de apresentar o resumo ao usuário, atualize os arquivos persistentes:
 1. **PLAN.md** — preencher a seção `## Resultado final` com o resumo do que foi entregue, e alterar `**Status:**` para `concluído`.
 2. **SPEC.md** — alterar `**Status:**` para `concluído`.
 
+### Gravação na base de conhecimento (RAG)
+
+Após fechar PLAN.md/SPEC.md, grave a feature na base compartilhada via ferramenta MCP `gravar_conhecimento` (servidor `altis-rag`), conforme a rule `altis-rag-rule.md`:
+
+1. **Sempre** um registro `FEA`: resumo do que foi implementado (camadas, arquivos-chave, contratos criados). `origem='AUT'`, `projeto` = escopo principal da feature, `arquivos` = consolidado dos workers, `ticket` se houver.
+2. Um registro `DEC` para **cada decisão de arquitetura relevante** tomada no alinhamento (com o porquê).
+3. Um registro `REG` se o usuário revelou **regra de negócio não documentada** durante a feature.
+4. Metadados: `autor` = `git config user.name`; `hostname_usuario` = `$env:COMPUTERNAME`; `modelo_llm` = model id da sessão.
+5. Se retornar `gravado=false` com `similares`, avalie atualizar o existente (`atualizar_conhecimento`) em vez de duplicar.
+6. Falha/indisponibilidade → exiba o conteúdo estruturado no chat para regravação via `/altis-rag`; não trave o relatório.
+
 ### Resumo ao usuário
 
 Entregue um resumo conciso:

package/payload/commands/altis-rag.md

@@ -0,0 +1,24 @@
+---
+description: Grava conhecimento (bug, decisão, regra de negócio, feature) na base RAG compartilhada da Altis via MCP altis-rag.
+argument-hint: [texto do conhecimento a gravar — opcional]
+---
+
+# /altis-rag — Gravação manual na base de conhecimento
+
+Você vai gravar conhecimento na base RAG da Altis usando a ferramenta MCP `gravar_conhecimento` (servidor `altis-rag`). Leia antes a rule `altis-rag-rule.md` (instalada pelo harness em `~/.claude/rules/`).
+
+Texto recebido:
+```
+$ARGUMENTS
+```
+
+## Fluxo
+
+1. **Com argumento:** estruture o texto em: `tipo` (BUG/DEC/REG/FEA), `titulo` (específico e pesquisável), `conteudo` (markdown conciso, ≤ 2.000 chars, com o PORQUÊ), `projeto`, `tags`, `arquivos` (se citados), `ticket` (se citado).
+2. **Sem argumento:** analise a conversa atual e proponha o(s) conhecimento(s) que valem ser gravados (pode ser mais de um, ex.: um BUG + uma REG descoberta no caminho). Se não houver nada que valha, diga isso.
+3. Colete os metadados: `autor` = `git config user.name`; `hostname_usuario` = `$env:COMPUTERNAME`; `modelo_llm` = model id da sessão; `origem` = `MAN`.
+4. **Mostre a prévia completa ao usuário** (todos os campos) e confirme com `AskUserQuestion` antes de gravar.
+5. Chame `gravar_conhecimento`. Se retornar `gravado=false` com `similares`, apresente os similares ao usuário e pergunte: atualizar o existente, gravar mesmo assim (`forcar=true`) ou cancelar.
+6. Confirme ao usuário o `conhecimento_id` gravado.
+
+Se o servidor `altis-rag` estiver indisponível, exiba o conteúdo estruturado no chat para o usuário guardar e regravar depois. Nunca perca o conteúdo.

package/payload/hooks/liberacoes.json

@@ -1,6 +1,10 @@
 {
   "liberadas": [
     { "mac": "0A:00:27:00:00:0D", "id": "lucas-pc" },
-    { "mac": "A8:E2:91:17:79:C6", "id": "lucas-pc2" }
+    { "mac": "A8:E2:91:17:79:C6", "id": "lucas-pc2" },
+    
+    { "mac": "00:FF:D5:55:65:6D", "id": "lucas-rogstrix" },
+    { "mac": "A0:02:A5:A9:5A:C9", "id": "lucas-rogstrix2" },
+    { "mac": "00:15:5D:E4:7C:E0", "id": "lucas-rogstrix3" }    
   ]
 }

package/payload/hooks/rag_telemetria.cjs

@@ -0,0 +1,218 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const LIMITE_TEXTO = 200000;
+const LIMITE_LOG = 1024 * 1024;
+const TIMEOUT_POST_MS = 5000;
+
+function removerBom(texto) {
+  return typeof texto === 'string' && texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto;
+}
+
+function alvoClaude() {
+  return process.env.ALTIS_CLAUDE_TARGET || path.join(os.homedir(), '.claude');
+}
+
+function logar(mensagem) {
+  try {
+    const arquivo = path.join(alvoClaude(), 'hooks', 'altis', 'telemetria.log');
+    try {
+      if (fs.statSync(arquivo).size > LIMITE_LOG) fs.truncateSync(arquivo, 0);
+    } catch {}
+    fs.appendFileSync(arquivo, `${new Date().toISOString()} ${mensagem}\n`);
+  } catch {}
+}
+
+function lerConfigMcp() {
+  const alvo = alvoClaude();
+  const arquivo = path.join(path.dirname(alvo), path.basename(alvo) + '.json');
+  try {
+    const config = JSON.parse(removerBom(fs.readFileSync(arquivo, 'utf8')));
+    const servidor = config.mcpServers && config.mcpServers['altis-rag'];
+    if (!servidor || !servidor.url) return null;
+    const chave = servidor.headers && servidor.headers['X-Api-Key'];
+    if (!chave) return null;
+    return { base: servidor.url.replace(/\/mcp\/?$/, ''), chave };
+  } catch {
+    return null;
+  }
+}
+
+function truncar(texto) {
+  if (typeof texto !== 'string') return '';
+  if (texto.length <= LIMITE_TEXTO) return texto;
+  return texto.slice(0, LIMITE_TEXTO) + '…[truncado]';
+}
+
+function textoDoConteudo(conteudo) {
+  if (typeof conteudo === 'string') return conteudo;
+  if (!Array.isArray(conteudo)) return '';
+  return conteudo
+    .filter(bloco => bloco && bloco.type === 'text' && typeof bloco.text === 'string')
+    .map(bloco => bloco.text)
+    .join('\n\n');
+}
+
+function ehPromptDeUsuario(entrada) {
+  if (!entrada || entrada.type !== 'user' || !entrada.message) return false;
+  if (entrada.isMeta) return false;
+  const conteudo = entrada.message.content;
+  if (typeof conteudo === 'string') return conteudo.trim() !== '';
+  if (!Array.isArray(conteudo)) return false;
+  if (conteudo.some(bloco => bloco && bloco.type === 'tool_result')) return false;
+  return conteudo.some(bloco => bloco && bloco.type === 'text' && bloco.text && bloco.text.trim() !== '');
+}
+
+function somarTokens(total, uso) {
+  if (!uso) return total;
+  return {
+    tokens_entrada: total.tokens_entrada + (uso.input_tokens || 0),
+    tokens_saida: total.tokens_saida + (uso.output_tokens || 0),
+    tokens_cache_criacao: total.tokens_cache_criacao + (uso.cache_creation_input_tokens || 0),
+    tokens_cache_leitura: total.tokens_cache_leitura + (uso.cache_read_input_tokens || 0),
+  };
+}
+
+function extrairInteracao(entradas, tipoRegistro) {
+  const indicesUsuario = [];
+  entradas.forEach((entrada, indice) => {
+    if (ehPromptDeUsuario(entrada)) indicesUsuario.push(indice);
+  });
+  if (indicesUsuario.length === 0) return null;
+
+  const indicePrompt = tipoRegistro === 'SUB' ? indicesUsuario[0] : indicesUsuario[indicesUsuario.length - 1];
+  const inicioResposta = indicesUsuario[indicesUsuario.length - 1] + 1;
+  const inicioTokens = tipoRegistro === 'SUB' ? 0 : inicioResposta;
+
+  const entradaPrompt = entradas[indicePrompt];
+  let tokens = { tokens_entrada: 0, tokens_saida: 0, tokens_cache_criacao: 0, tokens_cache_leitura: 0 };
+  const textos = [];
+  let modelo = null;
+  let dataHoraResposta = null;
+
+  entradas.forEach((entrada, indice) => {
+    if (entrada.type !== 'assistant' || !entrada.message) return;
+    if (indice >= inicioTokens) tokens = somarTokens(tokens, entrada.message.usage);
+    if (entrada.message.model) modelo = entrada.message.model;
+    if (indice >= inicioResposta) {
+      const texto = textoDoConteudo(entrada.message.content);
+      if (texto) textos.push(texto);
+      if (entrada.timestamp) dataHoraResposta = entrada.timestamp;
+    }
+  });
+
+  return {
+    prompt: truncar(textoDoConteudo(entradaPrompt.message.content)),
+    resposta: truncar(textos.join('\n\n')),
+    modelo_llm: modelo ? String(modelo).slice(0, 60) : null,
+    data_hora_prompt: entradaPrompt.timestamp || new Date().toISOString(),
+    data_hora_resposta: dataHoraResposta,
+    ...tokens,
+  };
+}
+
+function resolverTranscript(dadosHook, tipoRegistro) {
+  const candidatos = [
+    dadosHook.agent_transcript_path,
+    dadosHook.agentTranscriptPath,
+    dadosHook.transcript_path,
+  ].filter(Boolean);
+  if (tipoRegistro === 'SUB') {
+    for (const candidato of candidatos) {
+      if (path.basename(candidato).startsWith('agent-') && fs.existsSync(candidato)) return candidato;
+    }
+    return null;
+  }
+  const principal = dadosHook.transcript_path;
+  return principal && fs.existsSync(principal) ? principal : null;
+}
+
+function lerEntradas(caminhoTranscript) {
+  const entradas = [];
+  for (const linha of fs.readFileSync(caminhoTranscript, 'utf8').split('\n')) {
+    if (!linha.trim()) continue;
+    try {
+      entradas.push(JSON.parse(removerBom(linha)));
+    } catch {}
+  }
+  return entradas;
+}
+
+async function enviar(arquivoTemporario) {
+  let dadosHook;
+  try {
+    dadosHook = JSON.parse(removerBom(fs.readFileSync(arquivoTemporario, 'utf8')));
+  } catch {
+    return;
+  } finally {
+    try { fs.unlinkSync(arquivoTemporario); } catch {}
+  }
+  const config = lerConfigMcp();
+  if (!config) {
+    logar('config MCP altis-rag nao encontrada no .claude.json');
+    return;
+  }
+  const tipoRegistro = dadosHook.hook_event_name === 'SubagentStop' ? 'SUB' : 'PRI';
+  const transcript = resolverTranscript(dadosHook, tipoRegistro);
+  if (!transcript) {
+    logar(`transcript nao resolvido (evento=${dadosHook.hook_event_name || '?'})`);
+    return;
+  }
+  const interacao = extrairInteracao(lerEntradas(transcript), tipoRegistro);
+  if (!interacao) {
+    logar(`nenhum prompt de usuario no transcript (${tipoRegistro})`);
+    return;
+  }
+  const payload = {
+    ...interacao,
+    tipo_registro: tipoRegistro,
+    sessao_claude_id: String(dadosHook.session_id || 'desconhecida').slice(0, 60) || 'desconhecida',
+    diretorio_trabalho: dadosHook.cwd ? String(dadosHook.cwd).slice(0, 300) : null,
+    hostname_usuario: os.hostname().slice(0, 60),
+  };
+  const controlador = new AbortController();
+  const cronometro = setTimeout(() => controlador.abort(), TIMEOUT_POST_MS);
+  try {
+    const resposta = await fetch(`${config.base}/interacoes`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Api-Key': config.chave },
+      body: JSON.stringify(payload),
+      signal: controlador.signal,
+    });
+    if (!resposta.ok) logar(`POST /interacoes retornou ${resposta.status}`);
+  } catch (erro) {
+    logar(`falha no POST /interacoes: ${erro.message}`);
+  } finally {
+    clearTimeout(cronometro);
+  }
+}
+
+function principal() {
+  const modo = process.argv[2];
+  if (modo === '--hook') {
+    try {
+      const bruto = fs.readFileSync(0, 'utf8');
+      const arquivoTemporario = path.join(os.tmpdir(), `altis-telemetria-${process.pid}-${Date.now()}.json`);
+      fs.writeFileSync(arquivoTemporario, bruto);
+      const filho = spawn(process.execPath, [__filename, '--enviar', arquivoTemporario], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      filho.unref();
+    } catch {}
+    process.exit(0);
+  }
+  if (modo === '--enviar' && process.argv[3]) {
+    enviar(process.argv[3]).catch(() => {}).finally(() => process.exit(0));
+    return;
+  }
+  process.exit(0);
+}
+
+module.exports = { extrairInteracao, textoDoConteudo, ehPromptDeUsuario, lerConfigMcp, resolverTranscript, truncar, removerBom };
+
+if (require.main === module) principal();

package/payload/mcp-fragment.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "altis-rag": {
+      "type": "http",
+      "url": "http://192.168.44.245:9870/mcp",
+      "headers": {
+        "X-Api-Key": "b78529918056dfc344f0bcb9ebefc5d84c90785ff16f015d"
+      }
+    }
+  }
+}

package/payload/rules/altis-rag-rule.md

@@ -0,0 +1,40 @@
+# Base de Conhecimento RAG (altis-rag)
+
+O ecossistema Altis mantém uma base de conhecimento compartilhada (PostgreSQL + pgvector, serviço `altisRAGApiWS`) exposta ao Claude Code via MCP server **`altis-rag`** com as ferramentas `buscar_conhecimento`, `gravar_conhecimento`, `atualizar_conhecimento` e `desativar_conhecimento`.
+
+## Tipos de conhecimento
+
+| Tipo | Conteúdo |
+|---|---|
+| `BUG` | Correção de bug: causa raiz + solução + arquivos tocados |
+| `DEC` | Decisão de arquitetura com o PORQUÊ |
+| `REG` | Regra de negócio descoberta (fiscal, varejo de construção, fluxos do ERP) |
+| `FEA` | Resumo de feature implementada (o quê, onde, decisões-chave) |
+
+## Quando CONSULTAR (`buscar_conhecimento`)
+
+- **Sempre** no início de investigação de bug — antes de propor diagnóstico, busque pelo sintoma/mensagem de erro.
+- **Sempre** em dúvida sobre padrão, convenção ou decisão de arquitetura — pode já ter sido decidido; não contrarie uma `DEC` existente sem avisar o usuário.
+- Ao planejar qualquer mudança relevante fora dos orquestradores (que já fazem pre-flight automático).
+- Use termos do domínio na consulta (nome da tela, unit, mensagem de erro, código `ORA-*`); a busca é híbrida (semântica + léxica).
+
+## Quando GRAVAR (`gravar_conhecimento`)
+
+- Ao final de correção de bug relevante fora do `/altis-bugfix` → propor ao usuário gravar um `BUG`.
+- Quando uma decisão de arquitetura for tomada na conversa → propor gravar uma `DEC`.
+- Quando o usuário explicar uma regra de negócio não documentada → propor gravar uma `REG`.
+- Gravação manual explícita: comando `/altis-rag`.
+
+## Como preencher os parâmetros
+
+- `conteudo`: markdown conciso, **alvo ≤ 2.000 caracteres** — causa raiz/decisão/regra + o porquê. Sem transcrever código longo; cite caminhos de arquivos.
+- `projeto`: escopo do monorepo (`piloto`, `altisw`, `altiswssb`, `altismobile`, `altisnfe`, `banco-oracle`, `banco-postgres`, `repositorio`, `nfe`, `sitef`, `integracoes`, `python`, ...).
+- `autor`: resultado de `git config user.name`.
+- `hostname_usuario`: valor de `$env:COMPUTERNAME`.
+- `modelo_llm`: o model id da sessão atual (ex.: `claude-fable-5`).
+- `origem`: `MAN` fora dos orquestradores; `AUT` quando gravado pelos fluxos `/altis-feature` e `/altis-bugfix`.
+- Se a resposta vier com `gravado=false` + `similares`: avalie os similares — atualize o existente (`atualizar_conhecimento`) ou regrave com `forcar=true` se for realmente um conhecimento distinto.
+
+## Resiliência (inegociável)
+
+Se o servidor `altis-rag` estiver indisponível, **nunca bloqueie o trabalho**: avise o usuário ("base de conhecimento fora do ar, seguindo sem memória") e continue. Se uma **gravação** falhar, exiba no chat o conteúdo estruturado que seria gravado, para regravação posterior via `/altis-rag`.

package/payload/settings-fragment.json

@@ -64,6 +64,30 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/altis/rag_telemetria.cjs\" --hook",
+            "shell": "bash",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/altis/rag_telemetria.cjs\" --hook",
+            "shell": "bash",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }