Gerar esquemas de comandos para agentes de IA a partir dos comandos e flags reais

## Altere o registro e os geradores, não os arquivos gerados Trate as orientações do repositório como um contrato para os arquivos dentro do escopo delas. Preserve trabalhos não relacionados, aplique o formatador da linguagem a cada arquivo-fonte modificado e altere somente a menor entrada responsável que seja necessária para obter o comportamento solicitado. Identifique as entradas oficiais antes de editar. Um registro de comandos revisado deve ser responsável pela identidade estável dos comandos, pelos caminhos principais, pelos aliases e pela navegação. A árvore de comandos executável deve determinar se um caminho existe, se pode ser executado e quais sinalizadores aceita. Catálogos gerados e metadados de agentes são saídas, não superfícies de edição; altere as entradas de origem e os geradores e depois gere-os novamente. Execute a compilação, a suíte completa de testes, a geração, as verificações de divergência, as verificações de políticas e os testes direcionados de comandos definidos pelo repositório que cubram a mudança. Revise a diferença gerada e rejeite reescritas não relacionadas. ## Crie os esquemas em um só sentido e vincule cada comando uma vez Mantenha a resolução do esquema direcionada: 1. Construa a árvore de comandos e os sinalizadores realmente executáveis. 2. Combine o registro de identidade revisado com as sobreposições de metadados revisadas antes da vinculação. 3. Resolva tipos e mapeamentos de parâmetros, estados obrigatórios, valores padrão e restrições entre parâmetros. 4. Resolva a seleção do agente e a semântica de segurança, interface e barreiras de execução conforme a precedência de fontes declarada. 5. Vincule cada comando exatamente uma vez em uma única especificação tipada de ferramenta e em um índice. 6. Publique catálogos, exportações completas, resumos e metadados gerados somente a partir dessa fonte tipada. Depois da vinculação, não reabra anotações, registros de origem, catálogos anteriores nem JSON gerado para reparar ou resolver novamente a identidade. Um carregador de produção que decodifica um instantâneo incorporado é um limite de entrega, não uma segunda etapa de resolução de fontes. Ele nunca deve criar nem reparar comandos, sinalizadores, entradas de registro ou entradas de geração posteriores. Preserve o contrato de transmissão publicado, a menos que uma mudança versionada seja autorizada explicitamente. O alinhamento arquitetural com outro sistema não justifica uma mudança de formato sem versão. ## Verifique nos dois sentidos se cada comando e cada esquema se correspondem O vinculador deve rejeitar um caminho de comando ausente ou não executável, colisões de aliases e declarações de identidade nativas que não correspondam ao registro efetivo. Uma declaração de identidade nativa ausente pode ser aceita quando as anotações forem verificações de consistência, e não fontes alternativas de identidade. Imponha a cobertura nas duas direções: 1. Toda ferramenta de esquema entregue, incluindo sua projeção no catálogo, deve ser resolvida para um comando executável. 2. Toda folha de comando pública e executável deve ser resolvida para o esquema ou aparecer em uma exclusão exata, revisada e com motivo não vazio. Nunca use exclusões por prefixo ou curinga, pois elas podem ocultar comandos futuros. Exclusões obsoletas, inválidas ou duplicadas devem fazer a geração falhar, e uma exclusão deve ser retirada quando seu comando entrar no esquema. Trate o registro revisado como a única fonte de identidade estável e navegação, e a árvore executável como a fonte de verdade sobre caminhos, capacidade de execução e sinalizadores. Execute testes de completude reversa sempre que a árvore de comandos mudar. ## Separe os metadados de segurança dos textos de seleção do agente Divida as entradas escritas por pessoas conforme a responsabilidade. Os metadados controlam efeitos, risco, confirmação, idempotência, interfaces, barreiras de execução e sobreposições opcionais de parâmetros. A seleção controla resumos para agentes, orientações positivas e negativas de roteamento, exemplos e roteamento de produtos. Um índice deve apenas mapear identificadores de produtos para esses arquivos. Não misture campos entre esses blocos. Toda entrada escrita deve ser revisada explicitamente, incluir um motivo concreto de revisão e referências de evidências e ser a menor entrada que expresse o comportamento visível para o usuário. O texto de seleção deve explicar a intenção de acionamento, o roteamento entre comandos relacionados e os resultados esperados, em vez de repetir um resumo de comando. Resolva as evidências conforme a precedência declarada: primeiro os fatos do ambiente de execução, depois o esquema de interface ativo, os metadados de interface fixados e, por fim, a documentação de habilidades apenas como evidência. Quando a descoberta ativa usar credenciais pessoais, nunca exiba nem registre credenciais de acesso em um commit. Se a descoberta ativa falhar, registre a falha, use as evidências alternativas aprovadas e não invente uma interface nem um procedimento remoto. As sobreposições de parâmetros devem apontar para uma folha pública e executável exata e para sinalizadores reais. Elas podem refinar descrições, mapeamentos de interface, estados obrigatórios e requisitos condicionais, mas não devem criar comandos ou sinalizadores, definir uma interface nem anunciar um procedimento remoto desconhecido. ## Recrie todas as saídas do zero e verifique se coincidem Trate a geração como uma reconstrução completa e determinística do instantâneo, não como uma correção incremental sobre um catálogo anterior. Leia novamente todas as entradas revisadas, retire metadados de produtos gerados que tenham ficado obsoletos e reescreva as projeções exatas de saída. Arquivos gerados nunca devem se tornar entradas de mesclagem, e as proteções por byte devem falhar se a geração alterar entradas escritas ou o registro revisado. Use a mesma especificação tipada de ferramenta já resolvida para todas as projeções. A carga útil de uma folha deve ser igual à entrada correspondente na exportação completa e no catálogo, enquanto os resumos gerais e de grupo devem ser iguais à projeção resumida da mesma ferramenta. Uma consulta por alias pode alterar somente os campos de visualização específicos do alias; ela não deve resolver novamente nem modificar o contrato do comando. Para cada ferramenta e campo de parâmetro entregues, o valor de procedência selecionado deve ser exatamente igual ao valor entregue. Verificar apenas o nome da fonte, a quantidade de candidatos, a presença do campo ou o hash é insuficiente. Execute a geração, as verificações da veracidade da confirmação em execução, os testes de completude reversa, os testes direcionados de comandos e as verificações finais do carregador incorporado. Revise todas as diferenças resultantes antes de aceitar o instantâneo. ## Valide exemplos e simulações sem pular etapas nem usar --yes Armazene no máximo dois exemplos revisados por ferramenta. Os exemplos devem usar um caminho principal ou alias real, sinalizadores aceitos, argumentos posicionais obrigatórios e todas as restrições efetivas `require-one-of`, `require-together` e `mutual-exclusion`. Não inclua comentários de shell nem sinalizadores que contornem a confirmação, como `--yes`. Todo exemplo deve passar na validação do contrato em relação ao comando vinculado. A ausência de um valor obrigatório, a violação de uma restrição, um erro de execução ou um erro de resolução de interface são defeitos do contrato, não motivos para ignorar o exemplo. A execução de exemplos em tempo de execução é opcional e permitida somente quando a ferramenta tipada final publica uma capacidade explícita e revisada de simulação. Os metadados de risco e confirmação não devem fabricar suporte a prévias. Uma disposição manual revisada pode restringir uma capacidade de simulação existente a um índice de exemplo exato que comece em zero, mas deve usar um código de motivo aprovado, apresentar um motivo concreto e nunca transformar a validação comum do contrato em uma omissão. Nunca capture uma falha de simulação para rebaixá-la dinamicamente a uma validação somente do contrato. Execute barreiras abrangentes do contrato por padrão; com o comando real, execute apenas o subconjunto apto para simulação, usando o estado do usuário isolado e proxies bloqueados. Trate mudanças nas contagens estáveis de execução como mudanças de contrato sujeitas a revisão. ## Teste qual comando a IA escolhe sem enviar as respostas esperadas Trate todo cenário de seleção positivo como uma afirmação de que seu comando revisado deve ser escolhido, e todo cenário negativo como uma afirmação de que esse comando não deve ser escolhido. Derive casos de teste tipados e determinísticos dos campos de seleção escritos, exija cobertura exata das ferramentas e comandos principais executáveis e rejeite expectativas ausentes, duplicadas ou contraditórias. A simples correspondência de texto não comprova compreensão semântica. Mantenha explicitamente opcionais as verificações de seleção com um modelo ativo. Ofereça um pequeno conjunto básico, um conjunto revisado completo e uma lista exata de casos. Envie ao avaliador somente identificadores de casos, o texto do cenário e uma tabela de candidatos do mesmo produto; mantenha localmente as afirmações esperadas e proibidas. Inclua na lista de permissões os endpoints HTTPS integrados do avaliador. Qualquer outro provedor HTTPS exige que sua URL base exata esteja na lista aprovada, e HTTP em texto simples só é aceitável para um servidor de teste de loopback. Nunca envie credenciais de API para um endpoint arbitrário em texto simples. A integração contínua normal deve permanecer determinística e não deve chamar um modelo. Suas barreiras bloqueantes são casos de teste reproduzíveis, vinculação de comandos, validade dos exemplos, procedência e igualdade da entrega final. ## Defina segurança e confirmação pela prioridade das fontes Resolva os metadados de segurança e parâmetros conforme a precedência de fontes, não escolhendo o valor que pareça mais rigoroso. Uma fonte revisada de prioridade mais alta pode aumentar ou reduzir intencionalmente o efeito, o risco, a confirmação, a idempotência, as descrições ou os mapeamentos. Preserve todos os candidatos e a fonte selecionada e faça os conflitos no mesmo nível de precedência falharem em vez de mesclá-los silenciosamente. Sinalizadores obrigatórios de comandos são um limite inferior inalterável: uma sobreposição pode tornar obrigatório um sinalizador opcional, mas nunca deve enfraquecer um requisito declarado pelo comando executável. Para o texto dos comandos, priorize as orientações revisadas específicas do comando, depois a ajuda do comando e, por fim, os metadados de interface; um texto genérico de procedimento remoto não deve substituir uma descrição especializada do comando. Não deduza um campo de segurança a partir de outro. Um efeito destrutivo ou risco alto não reescreve mecanicamente a confirmação. A confirmação deve corresponder à barreira de execução explícita e, quando a confirmação do usuário for obrigatória, ela deve ser obtida antes da adição de um sinalizador de desvio como `--yes`. Se a ajuda distribuída do comando e o esquema da folha divergirem, passe somente os sinalizadores aceitos pelo comando executável. Se as fontes de segurança entrarem em conflito, use a interpretação mais segura ou pare e informe a divergência do contrato. Verifique a semântica da confirmação por meio do carregador incorporado final e do caminho de consulta, não apenas em um teste unitário do gerador. ## Descubra os comandos por etapas e obtenha os dados com comandos reais Mantenha a descoberta comum progressiva: primeiro a visão geral, depois o produto ou grupo e, por fim, a folha. Reserve a exportação completa como contrato estável de compatibilidade e inclua parâmetros, restrições e semântica de segurança completos para cada ferramenta final, incluindo um objeto de parâmetros vazio para comandos sem sinalizadores. Uma exportação completa compacta não é uma referência completa de compatibilidade. A ajuda do comando determina se um caminho existe e quais sinalizadores o executável aceita. O esquema da folha determina a seleção do agente, o mapeamento e as restrições de parâmetros e a semântica de segurança e confirmação. Qualquer divergência é uma divergência do contrato, não uma permissão para adivinhar. Esquemas e ajuda descrevem comandos; eles não retornam dados de negócios. Depois da descoberta, execute o comando real apropriado de leitura, pesquisa ou listagem dentro das permissões confirmadas para obter os dados. Antes da entrega, confirme que a identidade dos comandos foi revisada, que a cobertura executável é bidirecional, que as exclusões são exatas, que os blocos escritos mantêm responsabilidades separadas, que a precedência de fontes foi preservada, que as saídas geradas continuam sendo apenas saídas, que os exemplos passam em seus contratos reais, que a confirmação corresponde às barreiras de execução e que todas as projeções são iguais à mesma fonte tipada.