@semacode/cli 1.5.27 → 1.5.29

package/dist/index.js

@@ -5,7 +5,7 @@ import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import pacoteCli from "../package.json" with { type: "json" };
-import { compilarCodigo, formatarCodigo, formatarDiagnosticos, lerArquivoTexto, temErros, } from "@sema/nucleo";
+import { compilarCodigo, formatarCodigo, formatarDiagnosticos, gerarRespostaValidacao, lerArquivoTexto, temErros, } from "@sema/nucleo";
 import { descreverEstruturaModulo } from "@sema/padroes";
 import { gerarDart } from "@sema/gerador-dart";
 import { gerarLua } from "@sema/gerador-lua";
@@ -18,6 +18,7 @@ import { carregarConfiguracaoProjeto, carregarProjeto, resolverAlvoPadrao, resol
 import { importarProjetoLegado, resumoImportacao } from "./importador.js";
 import { analisarDriftLegado, assistirRenomeacaoSemantica, gerarMapaImpactoSemantico, } from "./drift.js";
 import { resolverDocumentacaoObrigatoria, verificarDocumentacaoMudanca, } from "./docs.js";
+import { REGISTRO_COMANDOS } from "./comandos.js";
 const STARTER_IA = `Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo em backend e front consumer.
 
 Importante:
@@ -41,11 +42,11 @@ Importante:
 - se a tarefa envolver UI, prefira pedir Sema + React + TypeScript ou Sema + arquitetura de front-end
 - evite pedir HTML unico solto quando a intencao for testar a Sema de verdade
 
-Regras:
-- nao invente sintaxe fora da gramatica e dos exemplos oficiais
-- antes de qualquer acao, crie, edite ou remova o contrato .sema aplicavel; isso vale para Software, Author, Workflow, Ops, Game, Legal e Research
-- se a IA for pequena, nao tente abrir tudo de uma vez
-- use \`sema resumo\` e \`briefing.min.json\` antes de subir para o pacote completo
+Regras:
+- nao invente sintaxe fora da gramatica e dos exemplos oficiais
+- antes de qualquer acao, crie, edite ou remova o contrato .sema aplicavel; isso vale para Software, Author, Workflow, Ops, Game, Legal e Research
+- se a IA for pequena, nao tente abrir tudo de uma vez
+- use \`sema resumo\` e \`briefing.min.json\` antes de subir para o pacote completo
 - trate \`ir --json\` como fonte de verdade semantica
 - trate \`briefing.json\` como plano de intervencao antes de editar projeto vivo
 - trate \`diagnosticos --json\` como fonte de correcao
@@ -113,19 +114,20 @@ Trate a Sema como protocolo de governanca semantica e linguagem de intencao feit
 
 Fontes de verdade, em ordem:
 1. se o projeto expuser \`SEMA_CONTEXT.md\`, comece por ele
-2. \`SEMA_BRIEF.md\`
-3. \`SEMA_INDEX.json\`
-4. README do projeto
-5. gramatica e documentacao de sintaxe da Sema
-6. especificacao semantica da linguagem
-7. exemplos oficiais, com prioridade para o vertical de pagamento
-8. \`sema resumo\` e \`briefing.min.json\` quando a IA for pequena
-9. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
-
-Regras de operacao:
-- contrato vem antes da acao: crie, edite ou remova o .sema aplicavel antes de codigo, docs operacionais, texto Author, workflow, jogo, pesquisa, legal ou ops
-- preserve o significado semantico
-- use o formatador oficial da Sema como fonte unica de estilo
+2. \`AGENT_CONTEXT_PACK.json\`
+3. \`SEMA_BRIEF.md\`
+4. \`SEMA_INDEX.json\`
+5. \`AGENTS.md\`
+6. README do projeto
+7. gramatica e documentacao de sintaxe da Sema
+8. exemplos oficiais, com prioridade para o vertical de pagamento
+9. \`sema resumo\` e \`briefing.min.json\` quando a IA for pequena
+10. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
+
+Regras de operacao:
+- contrato vem antes da acao: crie, edite ou remova o .sema aplicavel antes de codigo, docs operacionais, texto Author, workflow, jogo, pesquisa, legal ou ops
+- preserve o significado semantico
+- use o formatador oficial da Sema como fonte unica de estilo
 - use diagnosticos estruturados como contrato de correcao
 - use a IR como fonte de verdade semantica quando houver duvida
 - use predicados canonicos como normalizacao opcional, preservando a forma original
@@ -243,10 +245,10 @@ Se houver duvida, siga os exemplos oficiais e mantenha a separacao:
 `;
 const PROMPT_IA_SEMA_PRIMEIRO = `Quero que voce trabalhe no modo "Sema primeiro".
 
-Regra principal:
-- modele primeiro o dominio em arquivos \`.sema\`
-- se a intencao mudar, crie, edite ou remova o contrato antes de qualquer acao operacional
-- so depois proponha ou gere codigo de aplicacao derivado disso
+Regra principal:
+- modele primeiro o dominio em arquivos \`.sema\`
+- se a intencao mudar, crie, edite ou remova o contrato antes de qualquer acao operacional
+- so depois proponha ou gere codigo de aplicacao derivado disso
 
 Fluxo obrigatorio:
 1. entender o dominio pedido
@@ -330,8 +332,10 @@ Comandos uteis da CLI para esse fluxo:
 const DIRETORIO_CLI_ATUAL = path.dirname(fileURLToPath(import.meta.url));
 const VERSAO_CLI = pacoteCli.version;
 const requireRuntimeCli = createRequire(import.meta.url);
+const ARQUIVO_AGENT_CONTEXT_PACK = "AGENT_CONTEXT_PACK.json";
 const ARQUIVOS_CANONICOS_IA_RAIZ = [
     "llms.txt",
+    ARQUIVO_AGENT_CONTEXT_PACK,
     "SEMA_BRIEF.md",
     "SEMA_INDEX.json",
     "AGENTS.md",
@@ -356,6 +360,17 @@ const DOCUMENTOS_SUPORTE_IA = [
     "docs/rollback.md",
     "docs/extensao-vscode.md",
 ];
+const EXEMPLOS_OFICIAIS_AGENT_CONTEXT = [
+    "exemplos/calculadora.sema",
+    "exemplos/pagamento.sema",
+    "exemplos/profile_software.sema",
+    "exemplos/profile_workflow_n8n.sema",
+    "exemplos/profile_ops.sema",
+    "exemplos/profile_game.sema",
+    "exemplos/profile_legal.sema",
+    "exemplos/profile_research.sema",
+    "exemplos/author_obra_comum.sema",
+];
 function resolverImportadorNodeOpcional(especificador) {
     try {
         return requireRuntimeCli.resolve(especificador);
@@ -650,9 +665,15 @@ function normalizarModoResumo(valor) {
     }
     return "resumo";
 }
+const TIMEOUT_CHECAGEM_COMANDO_MS = 5_000;
 function comandoDisponivel(comando, argumentos = ["--version"]) {
-    const execucao = spawnSync(comando, argumentos, { stdio: "ignore", shell: process.platform === "win32" });
-    return (execucao.status ?? 1) === 0;
+    const execucao = spawnSync(comando, argumentos, {
+        stdio: "ignore",
+        shell: process.platform === "win32",
+        timeout: TIMEOUT_CHECAGEM_COMANDO_MS,
+        windowsHide: true,
+    });
+    return !execucao.error && execucao.signal === null && (execucao.status ?? 1) === 0;
 }
 const MCP_CLIENT_TOKEN_ENV_VAR = "SEMA_MCP_AUTH_TOKEN";
 const MCP_CLIENT_ENDPOINT_ENV_VAR = "SEMA_MCP_ENDPOINT";
@@ -1460,24 +1481,151 @@ function criarGuiaCapacidadeIa() {
     return {
         pequena: {
             descricao: "IA gratuita ou com contexto curto. Leia so o cartao semantico e o briefing minimo.",
-            artefatos: ["resumo.micro.txt", "briefing.min.json", "prompt-curto.txt"],
-            ordemLeitura: ["resumo.micro.txt", "briefing.min.json", "resumo.curto.txt"],
+            artefatos: ["agent-context-pack.json", "resumo.micro.txt", "briefing.min.json", "prompt-curto.txt"],
+            ordemLeitura: ["agent-context-pack.json", "resumo.micro.txt", "briefing.min.json", "resumo.curto.txt"],
             evitar: ["ast.json", "ir.json", "diagnosticos.json"],
         },
         media: {
             descricao: "IA com contexto medio. Aguenta resumo expandido, briefing minimo e drift.",
-            artefatos: ["resumo.curto.txt", "briefing.min.json", "drift.json", "prompt-curto.txt"],
-            ordemLeitura: ["resumo.curto.txt", "briefing.min.json", "drift.json", "resumo.md"],
+            artefatos: ["agent-context-pack.json", "resumo.curto.txt", "briefing.min.json", "drift.json", "prompt-curto.txt"],
+            ordemLeitura: ["agent-context-pack.json", "resumo.curto.txt", "briefing.min.json", "drift.json", "resumo.md"],
             evitar: ["ast.json"],
         },
         grande: {
             descricao: "IA com contexto grande ou tool use. Pode consumir o pacote completo.",
-            artefatos: ["README.md", "resumo.md", "briefing.json", "drift.json", "ir.json", "ast.json"],
-            ordemLeitura: ["README.md", "resumo.md", "briefing.json", "drift.json", "ir.json", "ast.json"],
+            artefatos: ["agent-context-pack.json", "README.md", "resumo.md", "briefing.json", "drift.json", "ir.json", "ast.json"],
+            ordemLeitura: ["agent-context-pack.json", "README.md", "resumo.md", "briefing.json", "drift.json", "ir.json", "ast.json"],
             evitar: [],
         },
     };
 }
+function criarAgentContextPack(guiaPorCapacidade) {
+    const fontes = [
+        {
+            caminho: "llms.txt",
+            tipo: "entrypoint",
+            prioridade: 1,
+            obrigatorio: true,
+            quandoUsar: "sempre no primeiro contato com o projeto",
+            incluirTextoBrutoQuando: "a IA precisa de orientacao compacta para operar o repositorio",
+        },
+        {
+            caminho: ARQUIVO_AGENT_CONTEXT_PACK,
+            tipo: "entrypoint",
+            prioridade: 2,
+            obrigatorio: true,
+            quandoUsar: "sempre antes de decidir quais documentos ou exemplos abrir",
+            incluirTextoBrutoQuando: "a IA precisa auditar regras, proibicoes, prioridades e fontes de verdade",
+        },
+        {
+            caminho: "SEMA_BRIEF.micro.txt",
+            tipo: "resumo",
+            prioridade: 3,
+            obrigatorio: true,
+            quandoUsar: "IA pequena, onboarding, chat remoto ou primeiro triage",
+            incluirTextoBrutoQuando: "a tarefa cabe em contexto curto",
+        },
+        {
+            caminho: "SEMA_BRIEF.curto.txt",
+            tipo: "resumo",
+            prioridade: 4,
+            obrigatorio: true,
+            quandoUsar: "IA media, mudanca pequena ou review rapido",
+            incluirTextoBrutoQuando: "o modulo alvo ainda nao esta claro pelo micro",
+        },
+        {
+            caminho: "SEMA_INDEX.json",
+            tipo: "indice",
+            prioridade: 5,
+            obrigatorio: true,
+            quandoUsar: "antes de abrir codigo cru ou escolher contrato alvo",
+            incluirTextoBrutoQuando: "a IA precisa mapear modulos, lacunas, riscos ou arquivos provaveis",
+        },
+        {
+            caminho: "AGENTS.md",
+            tipo: "operacional",
+            prioridade: 6,
+            obrigatorio: true,
+            quandoUsar: "antes de editar codigo, contrato, docs operacionais, release ou deploy",
+            incluirTextoBrutoQuando: "a IA precisa confirmar regras locais obrigatorias e prioridades do projeto",
+        },
+        {
+            caminho: "exemplos/",
+            tipo: "exemplos",
+            prioridade: 7,
+            obrigatorio: true,
+            quandoUsar: "antes de criar ou corrigir arquivo .sema, profile, Author, workflow, ops, game, legal ou research",
+            incluirTextoBrutoQuando: "a IA vai escrever sintaxe Sema ou comparar um contrato com formato oficial",
+        },
+        {
+            caminho: "docs/AGENT_STARTER.md",
+            tipo: "docs",
+            prioridade: 8,
+            obrigatorio: false,
+            quandoUsar: "onboarding de agente novo ou explicacao curta do fluxo",
+            incluirTextoBrutoQuando: "o agente remoto nao conhece Sema ainda",
+        },
+        {
+            caminho: "docs/sintaxe.md",
+            tipo: "docs",
+            prioridade: 9,
+            obrigatorio: false,
+            quandoUsar: "duvida de gramatica, blocos ou formato do DSL",
+            incluirTextoBrutoQuando: "a IA vai editar contrato e os exemplos nao bastam",
+        },
+        {
+            caminho: "contratos/",
+            tipo: "contrato",
+            prioridade: 10,
+            obrigatorio: true,
+            quandoUsar: "antes de qualquer implementacao ou alteracao de comportamento",
+            incluirTextoBrutoQuando: "a tarefa toca uma capacidade governada por contrato",
+        },
+    ];
+    return {
+        nome: "Agent Context Pack",
+        versao: 1,
+        objetivo: "Dar a agentes IA uma entrada curta, estruturada e auditavel antes de abrir codigo cru ou inventar contexto.",
+        ordemLeitura: [
+            "llms.txt",
+            ARQUIVO_AGENT_CONTEXT_PACK,
+            "SEMA_BRIEF.micro.txt",
+            "SEMA_INDEX.json",
+            "AGENTS.md",
+            "exemplos/",
+        ],
+        regrasObrigatorias: [
+            "Contrato vem antes da acao.",
+            "Leia AGENTS.md antes de editar codigo, contrato, docs operacionais, release ou deploy.",
+            "Use exemplos oficiais antes de criar ou corrigir sintaxe .sema.",
+            "Use SEMA_INDEX.json para escolher contrato, modulo e arquivos provaveis antes de abrir codigo cru.",
+            "Valide .sema alterado e rode drift antes de concluir.",
+            "Quando faltar contrato aplicavel, crie ou edite o contrato antes do codigo.",
+        ],
+        proibicoes: [
+            "Nao inventar sintaxe Sema fora da gramatica e dos exemplos oficiais.",
+            "Nao tratar README, texto livre ou codigo como fonte superior ao contrato.",
+            "Nao sincronizar segredos, .env, node_modules, builds, caches, uploads ou artefatos privados fora do escopo.",
+            "Nao publicar, deployar ou remover capacidade sem contrato, drift e verificacao.",
+            "Nao misturar repositorio publico e privado sem conferir docs de repositorios e AGENTS.md.",
+        ],
+        prioridades: [
+            "Menor artefato suficiente primeiro.",
+            "Contrato, indice e AGENTS antes de codigo cru.",
+            "Exemplos oficiais antes de nova sintaxe.",
+            "Diagnostico estruturado antes de opiniao livre.",
+            "Se risco ou escopo estiver ambigui, parar e pedir contrato/contexto.",
+        ],
+        fontes,
+        exemplosOficiais: [...EXEMPLOS_OFICIAIS_AGENT_CONTEXT],
+        textoBrutoSobDemanda: Object.fromEntries(fontes.map((fonte) => [fonte.caminho, fonte.incluirTextoBrutoQuando])),
+        guiaPorCapacidade: {
+            pequena: guiaPorCapacidade.pequena.ordemLeitura,
+            media: guiaPorCapacidade.media.ordemLeitura,
+            grande: guiaPorCapacidade.grande.ordemLeitura,
+        },
+    };
+}
 function coletarResumoSemanticoModulo(contexto) {
     const { arquivo, modulo, geradoEm, ir, briefing, drift } = contexto;
     const modoVerificacaoCodigo = contexto.modoVerificacaoCodigo ?? "codigo_completo";
@@ -1794,6 +1942,7 @@ ${resumoTexto}
 }
 function renderizarResumoProjetoMarkdown(geradoEm, modulos, guiaPorCapacidade) {
     const entradaCanonica = criarEntradaCanonicaProjeto(guiaPorCapacidade);
+    const agentContextPack = entradaCanonica.agentContextPack;
     const linhas = [
         "# SEMA_BRIEF",
         "",
@@ -1809,6 +1958,13 @@ function renderizarResumoProjetoMarkdown(geradoEm, modulos, guiaPorCapacidade) {
         `- IA media: ${entradaCanonica.porCapacidade.media.join(" -> ")}`,
         `- IA grande: ${entradaCanonica.porCapacidade.grande.join(" -> ")}`,
         "",
+        "## Agent Context Pack",
+        "",
+        `- Arquivo: \`${ARQUIVO_AGENT_CONTEXT_PACK}\``,
+        `- Objetivo: ${agentContextPack.objetivo}`,
+        `- Regras: ${agentContextPack.regrasObrigatorias.slice(0, 4).join(" | ")}`,
+        `- Fontes brutas sob demanda: ${agentContextPack.fontes.map((fonte) => fonte.caminho).slice(0, 7).join(", ")}`,
+        "",
         "## Guia por capacidade",
         "",
     ];
@@ -1831,15 +1987,17 @@ function renderizarResumoProjetoMarkdown(geradoEm, modulos, guiaPorCapacidade) {
     return `${linhas.join("\n").trim()}\n`;
 }
 function criarEntradaCanonicaProjeto(guiaPorCapacidade) {
+    const agentContextPack = criarAgentContextPack(guiaPorCapacidade);
     return {
         descricao: "Entrada canonica do repositorio para IA. O repo nao e human-first; a IA deve comecar por esses artefatos antes de abrir codigo cru.",
         ordemLeitura: [...ARQUIVOS_CANONICOS_IA_RAIZ],
         porCapacidade: {
-            pequena: ["llms.txt", "SEMA_BRIEF.micro.txt", "SEMA_INDEX.json", "AGENTS.md"],
-            media: ["llms.txt", "SEMA_BRIEF.curto.txt", "SEMA_INDEX.json", "AGENTS.md", "README.md"],
-            grande: ["llms-full.txt", "SEMA_BRIEF.md", "SEMA_INDEX.json", "AGENTS.md", "README.md"],
+            pequena: ["llms.txt", ARQUIVO_AGENT_CONTEXT_PACK, "SEMA_BRIEF.micro.txt", "SEMA_INDEX.json", "AGENTS.md"],
+            media: ["llms.txt", ARQUIVO_AGENT_CONTEXT_PACK, "SEMA_BRIEF.curto.txt", "SEMA_INDEX.json", "AGENTS.md", "README.md"],
+            grande: ["llms-full.txt", ARQUIVO_AGENT_CONTEXT_PACK, "SEMA_BRIEF.md", "SEMA_INDEX.json", "AGENTS.md", "README.md"],
         },
         docsSuporte: [...DOCUMENTOS_SUPORTE_IA],
+        agentContextPack,
         guiaPorCapacidade,
     };
 }
@@ -2086,13 +2244,15 @@ async function gerarArquivosResumoModuloIa(contexto, pastaBase) {
     const resumoMarkdown = renderizarResumoModuloMarkdown(resumoSemantico, "resumo", guiaPorCapacidade);
     const briefingMinimo = criarBriefingMinimo(resumoSemantico, "resumo", "curto");
     const promptCurto = criarPromptCurtoModulo(resumoSemantico, "mudanca", "curto", "pequena");
+    const agentContextPack = criarAgentContextPack(guiaPorCapacidade);
+    await writeFile(path.join(pastaBase, "agent-context-pack.json"), `${JSON.stringify(agentContextPack, null, 2)}\n`, "utf8");
     await writeFile(path.join(pastaBase, "resumo.micro.txt"), resumoMicro, "utf8");
     await writeFile(path.join(pastaBase, "resumo.curto.txt"), resumoCurto, "utf8");
     await writeFile(path.join(pastaBase, "resumo.md"), resumoMarkdown, "utf8");
     await writeFile(path.join(pastaBase, "briefing.min.json"), `${JSON.stringify(briefingMinimo, null, 2)}\n`, "utf8");
     await writeFile(path.join(pastaBase, "prompt-curto.txt"), promptCurto, "utf8");
     return {
-        artefatosCompactos: ["resumo.micro.txt", "resumo.curto.txt", "resumo.md", "briefing.min.json", "prompt-curto.txt"],
+        artefatosCompactos: ["agent-context-pack.json", "resumo.micro.txt", "resumo.curto.txt", "resumo.md", "briefing.min.json", "prompt-curto.txt"],
         guiaPorCapacidade,
     };
 }
@@ -2101,6 +2261,7 @@ async function gerarResumoProjetoIa(entrada, pastaSaidaOpcional, escreverNaRaiz
     const geradoEm = new Date().toISOString();
     const guiaPorCapacidade = criarGuiaCapacidadeIa();
     const entradaCanonica = criarEntradaCanonicaProjeto(guiaPorCapacidade);
+    const agentContextPack = entradaCanonica.agentContextPack;
     const modoVerificacaoCodigo = await detectarModoVerificacaoCodigo(contextoProjeto.baseProjeto, contextoProjeto.diretoriosCodigo);
     const fontesConclusao = await detectarFontesConclusaoSnapshot(contextoProjeto.baseProjeto);
     const resultadoDrift = await analisarDriftLegado(contextoProjeto);
@@ -2144,6 +2305,7 @@ async function gerarResumoProjetoIa(entrada, pastaSaidaOpcional, escreverNaRaiz
         conclusoesPorFonte: descreverFontesConclusao(fontesConclusao, modoVerificacaoCodigo),
         totalModulos: modulos.length,
         entradaCanonica,
+        agentContextPack,
         guiaPorCapacidade,
         modulos,
     };
@@ -2182,12 +2344,13 @@ async function gerarResumoProjetoIa(entrada, pastaSaidaOpcional, escreverNaRaiz
     await writeFile(path.join(pastaSaida, "SEMA_BRIEF.micro.txt"), micro, "utf8");
     await writeFile(path.join(pastaSaida, "SEMA_BRIEF.curto.txt"), curto, "utf8");
     await writeFile(path.join(pastaSaida, "SEMA_INDEX.json"), `${JSON.stringify(indexJson, null, 2)}\n`, "utf8");
+    await writeFile(path.join(pastaSaida, ARQUIVO_AGENT_CONTEXT_PACK), `${JSON.stringify(agentContextPack, null, 2)}\n`, "utf8");
     return {
         geradoEm,
         baseProjeto,
         pastaSaida,
         modoVerificacaoCodigo,
-        artefatos: ["SEMA_BRIEF.md", "SEMA_BRIEF.micro.txt", "SEMA_BRIEF.curto.txt", "SEMA_INDEX.json"],
+        artefatos: ["SEMA_BRIEF.md", "SEMA_BRIEF.micro.txt", "SEMA_BRIEF.curto.txt", "SEMA_INDEX.json", ARQUIVO_AGENT_CONTEXT_PACK],
         modulos,
         guiaPorCapacidade,
     };
@@ -2215,6 +2378,7 @@ async function gerarContextoIa(arquivoEntrada, pastaSaidaOpcional) {
 
 ## Arquivos gerados neste pacote
 
+- \`agent-context-pack.json\`
 - \`resumo.micro.txt\`
 - \`resumo.curto.txt\`
 - \`resumo.md\`
@@ -2229,26 +2393,38 @@ async function gerarContextoIa(arquivoEntrada, pastaSaidaOpcional) {
 
 ## Fluxo recomendado para o agente
 
+Antes de escolher arquivo de codigo, leia \`agent-context-pack.json\`. Ele declara regras obrigatorias, proibicoes, prioridades e quando abrir texto bruto como \`AGENTS.md\`, \`exemplos/\`, docs e contratos.
+
 ### IA pequena ou gratuita
 
-1. Ler \`resumo.micro.txt\`.
-2. Ler \`briefing.min.json\`.
-3. Se ainda couber contexto, ler \`resumo.curto.txt\`.
+1. Ler \`agent-context-pack.json\`.
+2. Ler \`resumo.micro.txt\`.
+3. Ler \`briefing.min.json\`.
+4. Se ainda couber contexto, ler \`resumo.curto.txt\`.
 
 ### IA media
 
-1. Ler \`resumo.curto.txt\`.
-2. Ler \`briefing.min.json\`.
-3. Ler \`drift.json\`.
-4. Se precisar, subir para \`resumo.md\`.
+1. Ler \`agent-context-pack.json\`.
+2. Ler \`resumo.curto.txt\`.
+3. Ler \`briefing.min.json\`.
+4. Ler \`drift.json\`.
+5. Se precisar, subir para \`resumo.md\`.
 
 ### IA grande ou com tool use
 
-1. Ler \`README.md\`.
-2. Ler \`resumo.md\`.
-3. Ler \`briefing.json\`.
-4. Ler \`drift.json\`.
-5. So depois abrir \`ir.json\` e \`ast.json\`.
+1. Ler \`agent-context-pack.json\`.
+2. Ler \`README.md\`.
+3. Ler \`resumo.md\`.
+4. Ler \`briefing.json\`.
+5. Ler \`drift.json\`.
+6. So depois abrir \`ir.json\` e \`ast.json\`.
+
+## Texto bruto sob demanda
+
+- Abra \`AGENTS.md\` antes de editar codigo, contrato, docs operacionais, release ou deploy.
+- Abra \`exemplos/\` antes de criar ou corrigir sintaxe \`.sema\`.
+- Abra \`docs/sintaxe.md\` quando exemplos nao bastarem para resolver a gramatica.
+- Abra \`contratos/\` antes de qualquer implementacao ou mudanca de comportamento.
 
 ## Fechamento
 
@@ -4872,6 +5048,59 @@ function validarTermosObrigatoriosArtefato(texto, checks) {
         });
     });
 }
+function artefatoPareceWebhookProfile(artefato, preset) {
+    return preset === "webhook" || /webhook|externalEventId|invoiceId|paidAt|paymentEvent|pagamento/i.test(artefato);
+}
+function artefatoParecePagamentoWebhookProfile(artefato) {
+    return /invoiceId|fatura|cobranc|paymentEvent|paidAt|pagamento/i.test(artefato) &&
+        /webhook|externalEventId|evento externo|evento de pagamento/i.test(artefato);
+}
+function artefatoPareceMultiTenantProfile(contrato, artefato) {
+    return /workspace|tenant|multi[- ]?tenant|multi[- ]?workspace|organiz/i.test(`${contrato}\n${artefato}`);
+}
+function presencaAutenticacaoWebhookProfile(artefato) {
+    return avaliarPresencaPositivaArtefato(artefato, /authorization|bearer|webhookSecret|webhook_secret|secret|assinatura|signature|hmac|x-webhook-secret|api[-_ ]?key|token/i);
+}
+function presencaWorkspaceWebhookProfile(artefato) {
+    return avaliarPresencaPositivaArtefato(artefato, /workspace(?:Id|Slug)?|workspace_id|workspace_slug|tenant(?:Id)?|tenant_id|organizationId|orgId|accountId|x-workspace(?:-slug|-id)?|isolamento por workspace/i);
+}
+function presencaIdempotenciaWorkspaceScopedProfile(artefato) {
+    const workspace = presencaWorkspaceWebhookProfile(artefato);
+    if (!workspace.atendido) {
+        return {
+            atendido: false,
+            trecho: workspace.trecho,
+            linha: workspace.linha,
+            coluna: workspace.coluna,
+            inicio: workspace.inicio,
+            fim: workspace.fim,
+            motivo: workspace.motivo ?? "idempotencia com externalEventId precisa de workspace/tenant positivo no mesmo artefato.",
+        };
+    }
+    const regexes = [
+        /@@unique\s*\(\s*\[[^\]]*(?:workspaceId|workspace_id|workspace|tenantId|tenant_id|tenant|organizationId|orgId|accountId)[^\]]*externalEventId[^\]]*\]\s*\)/i,
+        /@@unique\s*\(\s*\[[^\]]*externalEventId[^\]]*(?:workspaceId|workspace_id|workspace|tenantId|tenant_id|tenant|organizationId|orgId|accountId)[^\]]*\]\s*\)/i,
+        /(?:workspace|tenant|organization|orgId|accountId|x-workspace)[\s\S]{0,180}externalEventId/i,
+        /externalEventId[\s\S]{0,180}(?:workspace|tenant|organization|orgId|accountId|x-workspace)/i,
+    ];
+    for (const regex of regexes) {
+        const presenca = avaliarPresencaPositivaArtefato(artefato, regex);
+        if (presenca.atendido)
+            return presenca;
+    }
+    const negada = regexes
+        .map((regex) => avaliarPresencaPositivaArtefato(artefato, regex))
+        .find((presenca) => presenca.trecho);
+    return negada ?? { atendido: false };
+}
+function localizarIdempotenciaGlobalExternalEventProfile(artefato) {
+    return localizarRegexProfile(artefato, /\bexternalEventId\b[^\n\r;{}]*@unique/i) ??
+        localizarRegexProfile(artefato, /@@unique\s*\(\s*\[\s*externalEventId\s*\]\s*\)/i) ??
+        localizarRegexProfile(artefato, /externalEventId[\s\S]{0,120}global/i) ??
+        localizarRegexProfile(artefato, /global[\s\S]{0,120}externalEventId/i) ??
+        localizarRegexProfile(artefato, /externalEventId[\s\S]{0,120}(?:unico global|globalmente|global unique|unique global)/i) ??
+        localizarRegexProfile(artefato, /(?:unico global|globalmente|global unique|unique global)[\s\S]{0,120}externalEventId/i);
+}
 function avaliarArtefatoSoftwareProfile(contrato, artefato, maturidade, preset) {
     const regras = [
         { id: "software_eval_proibido", termo: "eval", regex: /\beval\s*\(/i, descricao: "codigo usa eval, risco basico de execucao dinamica", sugestao: "troque por parser explicito, tabela de operacoes ou validacao estruturada." },
@@ -4882,7 +5111,7 @@ function avaliarArtefatoSoftwareProfile(contrato, artefato, maturidade, preset)
         { id: "software_tls_desativado", termo: "TLS", regex: /rejectUnauthorized\s*:\s*false|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*["']?0/i, descricao: "codigo aparenta desativar validacao TLS/certificado", sugestao: "corrija cadeia de certificado ou use ambiente de teste isolado sem desligar TLS em producao." },
         { id: "software_shell_input_dinamico", termo: "shell", regex: /\b(exec|execSync|spawn|spawnSync)\s*\([\s\S]{0,160}(req\.|request\.|params|query|body|input|usuario|userInput)/i, descricao: "codigo aparenta executar shell com entrada dinamica", sugestao: "modele allowlist de comandos/argumentos e evite interpolar entrada do usuario." },
     ];
-    return regras.flatMap((regra) => {
+    const achados = regras.flatMap((regra) => {
         const achou = contemArtefatoProfile(artefato, regra.regex);
         if (!achou)
             return [];
@@ -4894,6 +5123,56 @@ function avaliarArtefatoSoftwareProfile(contrato, artefato, maturidade, preset)
                 : "warning";
         return [criarAchadoArtefatoProfile(regra.id, regra.descricao, false, severidade, trechoRegexProfile(artefato, regra.regex), regra.sugestao)];
     });
+    const pareceWebhook = artefatoPareceWebhookProfile(artefato, preset);
+    const pareceWebhookPagamento = artefatoParecePagamentoWebhookProfile(artefato);
+    const pareceMultiTenant = artefatoPareceMultiTenantProfile(contrato, artefato);
+    if (pareceWebhook && (pareceMultiTenant || pareceWebhookPagamento)) {
+        const auth = presencaAutenticacaoWebhookProfile(artefato);
+        if (!auth.atendido) {
+            achados.push(criarAchadoArtefatoProfile("software_webhook_sem_autenticacao", "webhook sensivel nao demonstra autenticacao, assinatura ou segredo", false, maturidade === "critical" ? "critical" : "blocking", auth.trecho ?? trechoRegexProfile(artefato, /webhook|externalEventId|invoiceId|paymentEvent|pagamento/i), "exija Authorization, assinatura HMAC ou segredo de webhook antes de aplicar efeito sensivel.", auth.motivo, {
+                linha: auth.linha,
+                coluna: auth.coluna,
+                inicio: auth.inicio,
+                fim: auth.fim,
+                risco: "webhook_sensivel_sem_auth",
+            }));
+        }
+        const workspace = presencaWorkspaceWebhookProfile(artefato);
+        if (!workspace.atendido) {
+            achados.push(criarAchadoArtefatoProfile("software_webhook_sem_workspace", "webhook multi-workspace nao demonstra fronteira de workspace/tenant", false, maturidade === "critical" ? "critical" : "blocking", workspace.trecho ?? trechoRegexProfile(artefato, /invoiceId|externalEventId|webhook|paymentEvent/i), "resolva workspace por header/slug/tenant autenticado e valide a invoice dentro desse escopo.", workspace.motivo, {
+                linha: workspace.linha,
+                coluna: workspace.coluna,
+                inicio: workspace.inicio,
+                fim: workspace.fim,
+                risco: "isolamento_multi_workspace_ausente",
+            }));
+        }
+    }
+    const externalEventGlobal = localizarIdempotenciaGlobalExternalEventProfile(artefato);
+    const externalEventPresente = /\bexternalEventId\b/i.test(artefato);
+    const idempotenciaScoped = presencaIdempotenciaWorkspaceScopedProfile(artefato);
+    if (externalEventGlobal || (pareceMultiTenant && pareceWebhook && externalEventPresente && !idempotenciaScoped.atendido)) {
+        achados.push(criarAchadoArtefatoProfile("software_external_event_idempotencia_global", "externalEventId parece unico globalmente em contexto multi-workspace", false, maturidade === "critical" ? "critical" : "blocking", externalEventGlobal?.trecho ?? idempotenciaScoped.trecho ?? trechoRegexProfile(artefato, /\bexternalEventId\b/i), "use chave composta por workspaceId/tenantId + externalEventId para idempotencia por workspace.", idempotenciaScoped.motivo, {
+            linha: externalEventGlobal?.linha ?? idempotenciaScoped.linha,
+            coluna: externalEventGlobal?.coluna ?? idempotenciaScoped.coluna,
+            inicio: externalEventGlobal?.inicio ?? idempotenciaScoped.inicio,
+            fim: externalEventGlobal?.fim ?? idempotenciaScoped.fim,
+            risco: "idempotencia_global_multi_tenant",
+        }));
+    }
+    const prismaManualSql = /schema\.prisma|\bPrisma\b|model\s+\w+\s*\{/i.test(artefato) &&
+        /CREATE\s+TABLE|setup-db\.ts|schema SQL manual|sql manual|duplica(?:r|do)? manualmente/i.test(artefato);
+    if (prismaManualSql) {
+        const severidade = maturidade === "draft" || maturidade === "prototype" ? "warning" : "blocking";
+        achados.push(criarAchadoArtefatoProfile("software_schema_prisma_duplicado", "artefato aparenta duplicar schema Prisma em SQL manual", false, maturidade === "critical" ? "critical" : severidade, trechoRegexProfile(artefato, /CREATE\s+TABLE|setup-db\.ts|schema SQL manual|sql manual|duplica(?:r|do)? manualmente/i), "derive o banco de migrations Prisma ou gere o bootstrap a partir do schema, evitando duas fontes de verdade.", undefined, { risco: "drift_schema_persistencia" }));
+    }
+    const eslintNextSemIgnore = /eslint\.config|npm run lint|lint/i.test(artefato) &&
+        /\.next/i.test(artefato) &&
+        !/ignores?\s*[:=][\s\S]{0,180}\.next|\.next\/\*\*|ignora\s+\.next/i.test(artefato);
+    if (eslintNextSemIgnore) {
+        achados.push(criarAchadoArtefatoProfile("software_lint_next_sem_ignore", "lint de Next.js parece varrer .next sem ignore explicito", false, "warning", trechoRegexProfile(artefato, /\.next/i), "adicione ignore para .next no flat config ou ajuste o script de lint.", undefined, { risco: "ruido_operacional_de_build" }));
+    }
+    return achados;
 }
 function avaliarArtefatoWorkflowProfile(contrato, artefato, preset) {
     const achados = validarTermosObrigatoriosArtefato(artefato, [
@@ -4910,6 +5189,47 @@ function avaliarArtefatoWorkflowProfile(contrato, artefato, preset) {
     if (preset === "webhook" && !avaliarPresencaPositivaArtefato(artefato, /webhook/i).atendido) {
         achados.push(criarAchadoArtefatoProfile("workflow_preset_webhook_sem_superficie", "preset webhook exige superficie webhook no artefato", false, "blocking", undefined, "nomeie endpoint/evento, payload e idempotencia."));
     }
+    const pareceWebhook = artefatoPareceWebhookProfile(artefato, preset);
+    if (pareceWebhook) {
+        const auth = presencaAutenticacaoWebhookProfile(artefato);
+        if (!auth.atendido) {
+            achados.push(criarAchadoArtefatoProfile("workflow_webhook_sem_autenticacao", "webhook real nao declara autenticacao, assinatura ou segredo", false, "blocking", auth.trecho ?? trechoRegexProfile(artefato, /webhook|externalEventId|invoiceId|pagamento/i), "declare secret, assinatura, token ou Authorization para o endpoint.", auth.motivo, {
+                linha: auth.linha,
+                coluna: auth.coluna,
+                inicio: auth.inicio,
+                fim: auth.fim,
+                risco: "webhook_sem_auth",
+            }));
+        }
+        const exigeWorkspace = artefatoPareceMultiTenantProfile(contrato, artefato) || artefatoParecePagamentoWebhookProfile(artefato);
+        if (exigeWorkspace) {
+            const workspace = presencaWorkspaceWebhookProfile(artefato);
+            if (!workspace.atendido) {
+                achados.push(criarAchadoArtefatoProfile("workflow_webhook_sem_workspace", "webhook multi-tenant nao declara workspace/tenant de fronteira", false, "blocking", workspace.trecho ?? trechoRegexProfile(artefato, /webhook|invoiceId|externalEventId|pagamento/i), "inclua workspaceSlug/workspaceId/tenant autenticado e valide efeitos dentro desse escopo.", workspace.motivo, {
+                    linha: workspace.linha,
+                    coluna: workspace.coluna,
+                    inicio: workspace.inicio,
+                    fim: workspace.fim,
+                    risco: "isolamento_multi_workspace_ausente",
+                }));
+            }
+        }
+        const externalEventGlobal = localizarIdempotenciaGlobalExternalEventProfile(artefato);
+        const externalEventPresente = /\bexternalEventId\b/i.test(artefato);
+        const idempotenciaScoped = presencaIdempotenciaWorkspaceScopedProfile(artefato);
+        if (externalEventGlobal || (externalEventPresente && !idempotenciaScoped.atendido && (artefatoPareceMultiTenantProfile(contrato, artefato) || artefatoParecePagamentoWebhookProfile(artefato)))) {
+            achados.push(criarAchadoArtefatoProfile("workflow_webhook_idempotencia_global", "webhook usa externalEventId sem escopo de workspace/tenant", false, "blocking", externalEventGlobal?.trecho ?? idempotenciaScoped.trecho ?? trechoRegexProfile(artefato, /\bexternalEventId\b/i), "modele idempotencia por workspaceId/tenantId + externalEventId.", idempotenciaScoped.motivo, {
+                linha: externalEventGlobal?.linha ?? idempotenciaScoped.linha,
+                coluna: externalEventGlobal?.coluna ?? idempotenciaScoped.coluna,
+                inicio: externalEventGlobal?.inicio ?? idempotenciaScoped.inicio,
+                fim: externalEventGlobal?.fim ?? idempotenciaScoped.fim,
+                risco: "idempotencia_global_multi_tenant",
+            }));
+        }
+        if (/invoiceId/i.test(artefato) && (!auth.atendido || !presencaWorkspaceWebhookProfile(artefato).atendido)) {
+            achados.push(criarAchadoArtefatoProfile("workflow_webhook_apenas_invoice_id", "webhook de pagamento parece aplicar efeito sensivel a partir de invoiceId sem fronteira suficiente", false, "critical", trechoRegexProfile(artefato, /invoiceId[\s\S]{0,160}(?:paidAt|amount|pago|pagamento|paid)|(?:paidAt|amount|pago|pagamento|paid)[\s\S]{0,160}invoiceId/i), "resolva workspace/autenticacao antes de buscar a invoice e rejeite invoice fora do escopo.", undefined, { risco: "efeito_sensivel_cross_tenant" }));
+        }
+    }
     return achados;
 }
 function avaliarArtefatoOpsProfile(artefato, preset) {
@@ -5743,18 +6063,10 @@ async function comandoValidar(entrada) {
 }
 async function comandoValidarJson(entrada) {
     const modulos = await carregarModulos(entrada);
-    const resultados = modulos.map((item) => ({
-        caminho: item.caminho,
-        modulo: item.resultado.modulo?.nome ?? null,
-        sucesso: !temErros(item.resultado.diagnosticos),
-        diagnosticos: item.resultado.diagnosticos,
-    }));
-    console.log(JSON.stringify({
-        comando: "validar",
-        sucesso: resultados.every((resultado) => resultado.sucesso),
-        resultados,
-    }, null, 2));
-    return resultados.every((resultado) => resultado.sucesso) ? 0 : 1;
+    const diagnosticos = modulos.flatMap((item) => item.resultado.diagnosticos);
+    const resultado = gerarRespostaValidacao(diagnosticos);
+    console.log(JSON.stringify(resultado, null, 2));
+    return resultado.valido ? 0 : 1;
 }
 async function comandoInspecionar(entrada, emJson, cwd = process.cwd()) {
     const contextoProjeto = await carregarProjeto(entrada, cwd);
@@ -6282,7 +6594,7 @@ async function comandoAjudaIa() {
     console.log("");
     console.log(renderizarSecaoAscii("Fluxo recomendado", [
         "Use `sema starter-ia` para um texto curto de onboarding.",
-        "Use `sema sync-ai-entrypoints` para regenerar `SEMA_BRIEF.*` e `SEMA_INDEX.json` na raiz.",
+        "Use `sema sync-ai-entrypoints` para regenerar `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.*` e `SEMA_INDEX.json` na raiz.",
         "Use `sema instalar-exemplos` para materializar `exemplos/` oficiais sem sobrescrever arquivos locais.",
         "Use `sema resumo <arquivo> --micro --para onboarding` para IA pequena.",
         "Use `sema prompt-curto <arquivo> --curto --para mudanca` para colar contexto em modelo gratuito.",
@@ -6458,7 +6770,15 @@ async function comandoPromptCurto(entrada, args, emJson) {
             : "SEMA_BRIEF.md";
     const contextoProjeto = await readFile(path.join(resumoProjeto.pastaSaida, arquivoResumo), "utf8");
     const capacidade = tamanho === "micro" ? "pequena" : tamanho === "curto" ? "media" : "grande";
-    const prompt = `Voce esta operando Sema em modo IA-first.
+    const prompt = `⚠️ REGRA OBRIGATÓRIA DE GOVERNANÇA:
+
+ANTES DE QUALQUER AÇÃO (editar, criar, deletar, executar, consultar, modificar):
+1. Chame sema_docs_impacto com sua intenção declarada
+2. Aguarde a resposta com as docs obrigatórias
+3. Leia as docs antes de agir
+4. Use sema_finalizar_mudanca para comprovar que leu as docs
+
+Você está operando Sema em modo IA-first.
 
 Isto e contexto comprimido para IA operar contrato semantico antes de tocar codigo vivo.
 
@@ -6466,8 +6786,9 @@ Capacidade alvo: ${capacidade}
 Modo da tarefa: ${modo}
 
 Regras:
+- ANTES DE TUDO: chame sema_docs_impacto com sua intenção declarada
 - comece pelo resumo compacto abaixo
-- se a tarefa pedir mais contexto, abra \`SEMA_INDEX.json\`
+- se a tarefa pedir mais contexto, abra \`AGENT_CONTEXT_PACK.json\` e depois \`SEMA_INDEX.json\`
 - nao tente ler o repo inteiro se o resumo ja disser onde tocar
 - preserve contrato, risco, lacuna e checks sugeridos
 
@@ -6702,6 +7023,12 @@ async function principal() {
     const cwd = process.cwd();
     const posicionais = obterPosicionais(resto);
     let codigoSaida = 0;
+    // --- Comandos registrados via REGISTRO_COMANDOS (mcp-client, bridge-config, contexto-chat, etc.) ---
+    const handlerRegistrado = REGISTRO_COMANDOS[comando];
+    if (handlerRegistrado) {
+        codigoSaida = await handlerRegistrado(posicionais, resto, possuiFlag(resto, "--json"));
+        process.exit(codigoSaida);
+    }
     switch (comando) {
         case "iniciar":
             codigoSaida = await comandoIniciar(cwd, normalizarTemplateIniciar(obterOpcao(resto, "--template")));