Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Garantia de meta

Status: Atual Escopo: checagens de aceitação da meta e frescor da fonte Última revisão: 2026-09-14 Responsável: mantenedores do runtime do AX Code

Planos de alteração de código produzidos pelo planejador de meta declaram checagens executáveis de aceitação. Cada checagem nomeia o resultado que cobre, o comando exato, a finalidade e o ambiente pretendido. O AX Code registra evidência de execução quando o agente executa verify_project com o id goalCheck da checagem.

{ "goalCheck": "invoice-parity" }

O comando vem do plano congelado da meta. O agente não pode substituí-lo por um comando diferente por esta chamada. As permissões já existentes de bash continuam valendo. Concluir a meta exige que a última tentativa de cada checagem declarada passe com meta, sessão, workspace, contrato e conteúdo da fonte correspondentes. A prosa de aceitação explica o resultado; ela não substitui checagens executadas. Execuções comuns de shell e checagens que foram puladas por completo não podem fornecer esta evidência.

Planos antigos de meta sem garantia conservam as regras anteriores de conclusão. Limpe e recrie uma meta antiga quando precisar do contrato novo; editar os requisitos congelados no lugar causa incompatibilidade de contrato. Uma bifurcação preserva o contrato, mas exige execuções novas das checagens na sessão nova.

Preparar um projeto de migração

Forneça a fonte legada autoritativa, ou exportações, com identificadores de revisão, um inventário delimitado de cobertura e scripts de checagem que falhem quando as asserções não puderem ser verificadas. Trate comentários e implementações anteriores de migração como pistas a investigar. Registre mudanças de comportamento aprovadas à parte dos requisitos de paridade com o legado.

Selecione checagens para as camadas que a alteração pedida de fato afeta:

Os scripts precisam afirmar a identidade do alvo antes de executar as checagens. Mantenha credenciais no mecanismo já existente de credencial do projeto, nunca no texto do plano, nos comandos ou nas descrições de alvo. Uma checagem deve devolver um código de saída diferente de zero para uma asserção que falhou, um ambiente ausente ou uma asserção exigida que foi pulada. Evite invólucros que mascarem falhas. O AX Code não consegue inferir asserções a partir de uma saída bem-sucedida do processo.

Para migrações grandes, organize o trabalho em lotes delimitados de fluxo de negócio e mantenha um inventário que ligue formulários, dependências, referências legadas e checagens de aceitação. Informe tanto o lote aceito quanto a cobertura restante. Passar num lote não conclui a migração inteira.

O que um plano registra

O planejador fornece um objeto assurance. Este fragmento ilustrativo supõe que o projeto tem a exportação de fonte e o script de checagem referidos:

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

Todos os ids de aceitação precisam estar cobertos. Os comandos executam a partir da raiz do workspace. O objeto de garantia é congelado com o contrato de aceitação. O agente recebe escopo validado, referências de fonte, ids de checagem e alvos declarados no contexto contínuo da meta. Contratos ausentes ou alterados produzem um aviso de restauração. Resumos gerados da conversa continuam falíveis; referências declaradas e rótulos de alvo são requisitos, não fatos observados de forma independente.

Intervalos git que medem o que esta meta mudou precisam usar {BASELINE} como o estado anterior. O planejador reescreve esse espaço reservado para o SHA do HEAD capturado quando o plano é enviado, então commits já existentes à frente de origin/main ou uma árvore de trabalho suja não podem tornar a meta impossível de concluir. Referências de rastreamento remoto (origin/main, @{u}, refs/remotes/…) são rejeitadas como esse estado anterior, a menos que o objetivo da meta nomeie o remoto. Registre caminhos já divergentes ou sujos em Riscos; não congele uma checagem de barreira que já esteja falhando, a menos que o objetivo seja corrigir essa falha.

Frescor e limites

As impressões digitais de fonte git incluem os bytes reais de arquivos rastreados e de arquivos não rastreados e não ignorados dentro do sourcePaths declarado. Caminhos explícitos de arquivo também incluem arquivos de configuração ignorados; caminhos de diretório conservam as regras de ignorar do Git. Listas mutáveis de checagem do plano da meta ficam de fora; os requisitos congelados delas são conferidos pelo resumo do contrato. Projetos que não são Git imprimem de forma recursiva o sourcePaths declarado, inclusive caminhos ausentes. Inclua nesse escopo toda fonte relevante, todo arquivo de configuração e todo script de checagem.

A impressão digital é limitada a 20,000 entradas e 128 MiB de conteúdo de arquivo. Fonte ligada, repositórios Git aninhados, arquivos especiais, caminhos que escapam, arquivos que mudam e leituras indisponíveis não podem produzir evidência fresca. Essas falhas bloqueiam a conclusão garantida. Artefatos de saída da checagem devem ir para um local ignorado, para que produzir um relatório não mude a fonte que está sendo verificada.

Arquivos ignorados que não foram nomeados de forma explícita, dependências fora do escopo da fonte, bancos e implantações precisam de asserções no comando do projeto. Um recibo registra uma observação no momento da execução; ele não prova que o estado externo permaneceu inalterado. Execute de novo as checagens afetadas depois de mudar configuração, bancos ou implantações. O AX Code não descobre sozinho todo o comportamento legado nem certifica paridade de migração.

Quando o planejamento executa

O planejamento é opcional nas duas superfícies. /goal <objective> e create_goal sem assure iniciam a meta na hora: ela não carrega critérios congelados de aceitação, e a conclusão é julgada pelo plano de trabalho (tarefas pendentes) mais uma verificação que passa depois da última alteração. /goal --assure <objective> e create_goal com assure: true executam primeiro o escritor de plano, e é isso que torna os recibos de checagem executada abaixo um requisito de conclusão.

Uma meta sem contrato diz isso onde quer que seja mostrada (/goal view, o diálogo da meta, as mensagens de controle), então a barreira de conclusão nunca é algo que você precise inferir. /goal replace conserva a garantia quando a meta substituída tem um contrato válido.

Contexto de planejamento e seleção de modelo

O planejamento da meta herda o modelo selecionado da sessão tanto por /goal quanto pela ferramenta create_goal. Variantes compatíveis de quem chama são preservadas. O escritor somente leitura recebe os requisitos originais recentes do usuário e as referências de anexo, com um orçamento de registro de 16 KiB. Um registro grande demais interrompe a inclusão de registros mais antigos, com um aviso, para que requisitos mais antigos não possam substituir em silêncio uma correção omitida; conteúdo de mídia no próprio texto não é tratado como evidência inspecionada. Forneça arquivos de fonte inspecionáveis para requisitos que só existam em mídia.

Progresso e bloqueios

get_goal inclui o status atual da checagem (passou, falhou, obsoleta, em execução ou ausente) e IDs recentes de evidência de ferramenta. A barreira de conclusão ainda exige recibos atuais e bem-sucedidos. Uma atualização bloqueada exige um tipo de bloqueio, um motivo, a mudança externa exigida, os IDs da evidência original e a confirmação de que não resta trabalho independente. Motivos de bloqueio são declarações do modelo apoiadas em registros inspecionáveis, não uma certificação de que um serviço externo continue indisponível.

Turnos concluídos que, de forma repetida, não produzem evidência nova e bem-sucedida de ferramenta recebem orientação de recuperação e depois pausam a meta, com o trabalho inacabado revelado. Resultados novos de pesquisa podem contar sem edições de fonte; reescritas de tarefas e resultados idênticos repetidos não contam. Isto é uma heurística delimitada, não prova de progresso semântico. /goal resume inicia outra tentativa. Chamadas de ferramenta geradas para uma meta anterior não podem encerrar a substituta. Uma meta criada por ferramenta fica disponível para atualizações de status depois que o modelo recebeu o resultado da criação no passo seguinte.

Revisar um plano existente

Use /goal revise <correction> para revisar de forma explícita uma meta congelada ativa, pausada ou bloqueada. Trabalho concluído e orçamentos esgotados exigem uma meta nova. O plano anterior e o resumo permanecem intactos. O plano revisado ganha uma identidade nova e um registro local de revisão preparada, ligando os dois resumos e a correção. A identidade atual da meta determina qual candidato foi de fato instalado; candidatos concorrentes que falharam podem permanecer em disco para inspeção. Recibos antigos permanecem no histórico e não podem satisfazer a revisão nova. O orçamento de tokens e o uso acumulado são transferidos; a revisão não concede um orçamento novo de gasto.

A revisão cancela a execução atual e pausa a meta enquanto prepara o plano novo. Se o planejamento falhar, o contrato anterior continua retomável; uma meta antes bloqueada conserva esse status. Uma pausa ou um cancelamento do usuário durante o planejamento impede a ativação. Uma substituição concorrente impede o candidato de assumir. Ferramentas do modelo não podem revisar em silêncio requisitos congelados. Revise o plano resultante e os critérios de aceitação dele; um comando executável, sozinho, não estabelece que as asserções cubram o pedido corrigido.

Resultados de revisão e alterações posteriores da fonte

Um log de revisão não vazio não estabelece revisão bem-sucedida. Para revisores externos exigidos, use uma checagem de posse do projeto que valide o código de saída real, a conclusão no terminal, a identidade da fonte ou do diff, e os achados finais ou um veredito explícito de ausência de achados. Logs só de aviso, raciocínio parcial e tempos esgotados precisam falhar. Guarde tentativas que falharam à parte, para diagnóstico.

Envios novos de alteração de código rejeitam checagens simples reconhecidas de presença e de inspeção de arquivo. Esta é uma proteção estreita de admissão, não uma prova semântica de comandos arbitrários de shell. Contratos congelados existentes conservam o esquema e o resumo; pontos de verificação avisam quando uma checagem mais antiga tem essa fraqueza.

O frescor da checagem da meta também imprime os caminhos de arquivo resolvidos informados por ferramentas bem-sucedidas de edição de arquivo durante a meta atual, inclusive cada resultado multiedit e caminhos omitidos da lista original de fonte. Edições posteriores nesses arquivos invalidam recibos anteriores. O contrato congelado e o resumo não mudam. Este rastreio usa metadados do resultado da ferramenta de arquivo; ele não infere efeitos colaterais arbitrários de shell nem cobertura de teste. Os limites já existentes de contenção do sistema de arquivos, de link, de tamanho e de contagem de arquivos continuam valendo.

A saída da checagem e os pontos de verificação da meta revelam caminhos adicionais. Se um comando congelado de teste omitir regressões necessárias, peça /goal revise <correction> e execute as checagens revisadas. Incluir um arquivo numa impressão digital prova frescor, não que um teste tenha exercitado esse arquivo. Prefira diretórios delimitados de fonte e comandos de teste que incluam regressões novas ao planejar uma varredura aberta de defeitos.

Aliases do workspace são normalizados para os caminhos de arquivo observados. Arquivos externos de rascunho não se tornam entradas de fonte do workspace; os pontos de verificação revelam que o conteúdo externo não é impresso. Estado externo exigido ainda precisa de verificação de posse do projeto.

Evidência de escopo do commit

Um git log <baseline>..HEAD -- <paths> não vazio só prova que um commit casa com o filtro. Ele não exclui arquivos sem relação nesse commit nem outros commits. Planos novos de alteração de código rejeitam asserções reconhecidas e isoladas de log git filtrado por caminho e não vazias; checagens congeladas mais antigas recebem orientação de revisão sem mudar o resumo nem a validação no momento da leitura.

Use um verificador de posse do projeto que confira a ancestralidade da linha de base, exija um intervalo não vazio e inspecione cada caminho alterado em cada commit, sem filtros de caminho. Inclua arquivos apagados e os dois lados de renomeações, trate commits de merge de forma explícita e valide à parte quaisquer propriedades exigidas de ramo ou de mensagem. Use /goal revise para fortalecer um contrato existente; não edite requisitos congelados.

Tamanho do plano e reenvio completo

O plano renderizado, inclusive Markdown e o JSON de garantia, precisa caber em 8,192 bytes UTF-8. Mire abaixo de 7,168 bytes. Se o envio passar do teto, encurte a prosa repetida e reenvie o objeto completo, inclusive kind e todos os campos exigidos. Preserve os ids e as checagens de aceitação; o runtime não trunca requisitos nem eleva o limite do leitor para aceitar um plano grande demais.

Recibos de revisão de animação da CLI local

O packages/ax-code/script/verify-cli-review-receipts.ts de posse do repositório confere artefatos round-* sob a raiz de recibo selecionada com --root. Cada rodada precisa de revision.txt, e cada um de grok, claude e codex precisa de exit.txt com 0 e um veredito final em stdout.jsonl (eventos de texto do Grok) ou stdout.txt (Claude/Codex). Conserve tentativas que falharam fora dos diretórios de rodada concluída; não transforme falhas em recibos de saída zero.

dispositions.json contém um array findings. Cada entrada nomeia round, cli, id, status (fixed ou rejected) e evidence não em branco. Entradas fixas exigem ainda um objeto regression com um caminho literal do repositório file sob packages/ax-code/test/cli/tui/ e o Vitest exato fullName. Disposições duplicadas ou vários vereditos ambíguos falham.

O verificador executa esses arquivos usando o Vitest instalado, com o padrão global de nova tentativa definido como zero (opções individuais de teste podem substituir esse padrão), e depois confere que cada asserção referida passou exatamente uma vez. Asserções ausentes, puladas, que falharam ou ambíguas fazem a verificação falhar. Isso prova que esses testes referidos passaram, não que as asserções cubram semanticamente o achado. Disposições rejeitadas permanecem como julgamentos registrados. Uma rodada final precisa casar com o HEAD atual; achados marcados como corrigidos exigem uma revisão mais nova e uma rodada de revisão. Alterações não enviadas de código-fonte, de teste ou de configuração do pacote central impedem a verificação. Mantenha a configuração local sem relação ax-code.json fora dos commits.

Para este repositório, vitest run --dir test/cli/tui preserva as exclusões da faixa normal ao varrer o diretório da TUI. Executores de grupo ainda podem selecionar arquivos exatos com AX_TEST_FILES; a seleção de diretório não desativa as exclusões.