{
  "marca": "kk-sa",
  "nome": "leia-llm",
  "galhos": [
    { "id": "1", "nome": "Contrato padronizado dos conectores QQ para LLMs" },
    { "id": "1.1", "nome": "Este arquivo é a referência operacional para LLMs criarem ou revisarem conectores padronizados no diretório conectores." },
    { "id": "1.2", "nome": "Todo conector deve ser um executável em conectores/<nome-do-conector>, com shebang quando necessário e permissão de execução." },
    { "id": "1.3", "nome": "O conector deve ser não interativo: não pedir entrada por teclado, não abrir prompt e não depender de sessão humana." },

    { "id": "2", "nome": "Comandos obrigatórios" },
    { "id": "2.1", "nome": "--ler-mensagem <arquivo-json>: recebe da escuta o arquivo de mensagem a processar." },
    { "id": "2.2", "nome": "--help: mostra uso, entradas aceitas, saídas geradas, códigos de saída e exemplos." },
    { "id": "2.3", "nome": "--sa: mostra ou referencia a árvore semântica do conector." },
    { "id": "2.4", "nome": "Chamadas inválidas devem escrever erro em STDERR e encerrar com código 2." },

    { "id": "3", "nome": "Formato da mensagem recebida" },
    { "id": "3.1", "nome": "id: identificador interno único da mensagem; deve ser preservado na resposta." },
    { "id": "3.2", "nome": "timestamp: data/hora de entrada em UTC, normalmente em formato ISO-8601." },
    { "id": "3.3", "nome": "mensagem: código do catálogo, por exemplo 003.json." },
    { "id": "3.4", "nome": "entrada: objeto validado pela API conforme escuta/catalogo-mensagens/<codigo>.json." },
    { "id": "3.5", "nome": "endresposta: URL opcional para envio de resposta por HTTP POST." },
    { "id": "3.6", "nome": "destino e destinatario: caminho lógico do conector, por exemplo conector/catalogo." },
    { "id": "3.7", "nome": "Campos desconhecidos não devem causar falha se os campos obrigatórios estiverem válidos." },
    { "id": "3.8", "nome": "O diretório ambiente-externo representa um espaço externo ao QQ, como se estivesse em outro servidor." },
    { "id": "3.9", "nome": "Em ambiente-externo encontram-se exemplos de programas que consomem as mensagens do catálogo e enviam respostas para o QQ." },

    { "id": "4", "nome": "Fluxo obrigatório de processamento" },
    { "id": "4.1", "nome": "Ler exatamente o arquivo recebido em --ler-mensagem." },
    { "id": "4.2", "nome": "Validar existência do arquivo, JSON válido e campos esperados antes de executar a ação." },
    { "id": "4.3", "nome": "Consultar escuta/catalogo-mensagens/<codigo>.json quando precisar confirmar entrada, saída ou ativação da mensagem." },
    { "id": "4.4", "nome": "Executar somente a ação correspondente ao conector e à mensagem do catálogo." },
    { "id": "4.5", "nome": "Não executar comandos arbitrários vindos da mensagem; quando shell for inevitável, validar lista permitida e escapar argumentos." },
    { "id": "4.6", "nome": "Gerar resposta JSON padronizada em sucesso e, quando houver id legível, também em erro de validação ou processamento." },
    { "id": "4.7", "nome": "Gravar resposta local de forma atômica em escuta/espaco/respostas/<id-sanitizado>.json." },
    { "id": "4.8", "nome": "Sanitizar id usado em nome de arquivo para impedir path traversal; permitir apenas letras, números, ponto, sublinhado e hífen." },
    { "id": "4.9", "nome": "Se endresposta estiver preenchido, enviar a resposta por HTTP POST com Content-Type application/json." },

    { "id": "5", "nome": "Formato mínimo da resposta" },
    { "id": "5.1", "nome": "status: ok ou erro." },
    { "id": "5.2", "nome": "conector: nome do conector executado." },
    { "id": "5.3", "nome": "mensagem: código da mensagem processada." },
    { "id": "5.4", "nome": "id: mesmo id recebido na mensagem." },
    { "id": "5.5", "nome": "timestamp_resposta: data/hora UTC da resposta." },
    { "id": "5.6", "nome": "Em sucesso, incluir no JSON os campos definidos em saida do catálogo da mensagem." },
    { "id": "5.7", "nome": "Não criar um campo literal chamado 'dados de saída', salvo se esse campo estiver definido no catálogo." },
    { "id": "5.8", "nome": "Em erro, incluir erro ou erros com mensagem clara e segura, sem vazar segredos." },
    { "id": "5.9", "nome": "envio_resposta: quando houver endresposta, registrar enviada, http, erro e retorno." },

    { "id": "6", "nome": "Códigos de saída do executável" },
    { "id": "6.1", "nome": "0: processamento concluído com sucesso; a escuta move a mensagem para concluidas." },
    { "id": "6.2", "nome": "2: erro de uso, argumento inválido, mensagem inválida ou entrada fora do padrão." },
    { "id": "6.3", "nome": "1 ou outro diferente de 0: falha de processamento; a escuta move a mensagem para erro." },
    { "id": "6.4", "nome": "Quando possível, erros com id conhecido também devem gerar resposta JSON local antes de encerrar." },

    { "id": "7", "nome": "Boas práticas obrigatórias" },
    { "id": "7.1", "nome": "Não alterar nem apagar o arquivo original da mensagem; a escuta controla movimentação." },
    { "id": "7.2", "nome": "Não usar segredos hardcoded; ler credenciais de local protegido quando necessário." },
    { "id": "7.2.1", "nome": "Credenciais, tokens e senhas para serviços externos usados por conectores devem ser mantidos em /etc/secretos/tokens-servicos-conectores." },
    { "id": "7.2.2", "nome": "Exemplo: um conector de e-mail pode ler, nesse diretório protegido, a senha ou token de acesso à plataforma do Gmail." },
    { "id": "7.2.3", "nome": "Os arquivos de autenticação devem ser separados por conector ou serviço e nunca devem ser gravados em conectores, catálogo, mensagens ou respostas." },
    { "id": "7.2.4", "nome": "Permissões esperadas: diretório /etc/secretos/tokens-servicos-conectores com dono root, grupo clip_access e modo 2770; arquivos de segredo preferencialmente com modo 0660." },
    { "id": "7.3", "nome": "Escrever erros em STDERR e mensagens normais em STDOUT." },
    { "id": "7.4", "nome": "Usar gravação atômica: escrever .tmp no mesmo diretório de destino, fechar o arquivo e renomear para .json." },
    { "id": "7.5", "nome": "Manter compatibilidade com chamadas diretas pela escuta via execv." },
    { "id": "7.6", "nome": "Usar timeouts em chamadas externas e tratar indisponibilidade de rede como erro controlado." },
    { "id": "7.7", "nome": "Produzir JSON UTF-8 válido, preferencialmente sem escapar barras e caracteres Unicode desnecessariamente." },

    { "id": "8", "nome": "Checklist para novo conector" },
    { "id": "8.1", "nome": "Criar conectores/<nome> com permissão executável." },
    { "id": "8.2", "nome": "Implementar --ler-mensagem, --help e --sa." },
    { "id": "8.3", "nome": "Criar ou atualizar escuta/catalogo-mensagens/<codigo>.json." },
    { "id": "8.4", "nome": "Mapear o destino em escuta/api/conect.json." },
    { "id": "8.5", "nome": "Testar execução manual com --help, --sa e --ler-mensagem." },
    { "id": "8.6", "nome": "Testar POST na public/api.php e confirmar resposta em escuta/espaco/respostas." },
    { "id": "8.7", "nome": "Testar callback quando endresposta for usado." },
    { "id": "8.8", "nome": "Confirmar que não há segredos gravados no código, no catálogo, nas mensagens ou nas respostas." }
  ],
  "recolhidos": [
  ]
}