@zaip-ai/cli 2.6.0 → 3.1.0

package/templates/.agents/zaip-aios/guides/23-orquestracao-de-modelos.md

@@ -1,512 +1,213 @@
 # Guia de orquestração de modelos e reasoning effort
 
-## Objetivo
-
-Este guia define como o ZAIP-AIOS recomenda modelo, `reasoning effort` e velocidade para cada trabalho. A política deve equilibrar quatro resultados:
-
-- alta assertividade na entrega;
-- baixo percentual de bugs e rework;
-- validação proporcional ao risco;
-- economia de tokens, custo e tempo total até a entrega verificada.
-
-Na implementação atual, a política suporta `manual`, `off` e `auto`. No projeto ZAIP-AIOS, `auto` está ativado somente para Executions originadas por SPEC ou PRD; Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex. `manual` continua disponível para rollback e permanece o default de novas instalações.
-
-Na política automática, Executions originadas por PRD ou SPEC solicitam velocidade `standard`, sem override para Fast. Em Conversation ou Task-first independente, a seleção de Fast pertence ao host/Codex; o ZAIP não a ativa, persiste nem herda. Velocidade do provider, paralelismo e tempo total até a tarefa aceita são medidas distintas.
-
-## Estado atual
-
-### Estado verificado do framework
-
-O schema canônico de `project.yaml` aceita `manual`, `off` e `auto`. O Agent Run registra agente, papel, pai, modelo e `reasoning_effort` planejados. O resolvedor aplica política e overrides quando a Run começa; Calls internas apenas herdam essa configuração e acumulam telemetria na própria Run.
-
-Uma mudança deliberada de modelo, effort, agente ou fase material exige uma nova Agent Run. Por isso, uma Task pode usar configurações diferentes em implementação, revisão e rework, desde que cada etapa possua sua própria Run relacionada. Retry técnico e retomada por checkpoint preservam a configuração original.
-
-### Modo manual
-
-Quando `model_orchestration.mode` estiver como `manual`, o ZAIP:
-
-1. usa modelo, esforço e velocidade somente quando estiverem explícitos no input ou contexto técnico do turno;
-2. classifica o trabalho;
-3. recomenda uma configuração;
-4. informa a recomendação antes de continuar;
-5. nunca altera a configuração automaticamente.
-
-O modo manual não usa hook nem tenta coletar a configuração efetiva no transcript. `default_model`, `default_effort` e `default_velocity` podem orientar uma recomendação, mas não comprovam o que o host executou. Quando modelo, effort ou velocidade efetivos não vierem de fonte observada, registre-os como indisponíveis/`unknown`; nunca os infira pelo comportamento aparente do modelo nem os substitua pelo default.
-
-Formato recomendado:
-
-```text
-Você está usando o modelo <modelo>, esforço <esforço> e velocidade <velocidade>.
-Esta tarefa é <lite|padrão|crítico>; recomendo esforço <esforço> e velocidade
-<velocidade> porque <motivos observáveis>. Caso concorde, cancele esta tarefa
-e faça a configuração manual no Codex.
-```
-
-### Modo automático por origem
-
-O modo automático resolve uma configuração antes de cada Agent Run elegível e preserva separadamente os valores planejados e os valores efetivamente observados. A decisão é metadado estruturado do runtime; instruções em linguagem natural como “use high effort” não garantem mudança real.
-
-O campo `automatic_sources` é a fronteira de aplicação. O contrato aceita exatamente `spec` e `prd`: somente as Tasks materializadas dentro dessas Executions recebem seleção automática, sempre com velocidade `standard`. Uma Execution originada diretamente de `task`, uma Conversation ou uma Task avulsa não recebe a política e não herda `default_model`, `default_effort` nem `default_velocity`; preserva os três valores escolhidos manualmente no Codex.
-
-Cada Task ou fase materialmente distinta deve executar em seu próprio Agent Run. Calls produzidas durante a Run usam o mesmo modelo e effort. Tasks paralelas podem usar configurações diferentes simultaneamente quando estiverem isoladas em Runs próprias.
-
-O modo automático é híbrido e governado: o modelo pode propor a configuração a partir dos metadados da Task elegível, mas um resolvedor determinístico limita a decisão à allowlist, aos caps e à precedência do projeto. Isso preserva a flexibilidade documentada pelo Codex sem transformar uma decisão de custo e qualidade em texto não auditável.
-
-### Escolha manual no Codex
-
-Um `.codex/config.toml` sem cabeçalho `zaip-managed` é tratado como overlay local do usuário. `adapters build` o preserva e `adapters check` o aceita sem mascarar drift nos hooks, regras, instruções e demais projeções gerenciadas. Isso impede que uma atualização do framework restaure silenciosamente um pin de modelo ou apague preferências locais.
-
-Os registros e perfis `zaip-agent-*` pertencem exclusivamente ao catálogo do projeto em `.agents/config/agents/catalog.yaml`. Para Codex, os perfis gerados ficam em `.agents/config/clients/codex/agents/*.toml`, e `.codex/config.toml` mantém apenas os registros que os referenciam e o bootstrap nativo. A inicialização não copia configuração de projeto para `~/.codex`; somente remove registros globais legados que reutilizem essas identidades técnicas e poderiam prevalecer ou conflitar com o projeto confiável.
-
-O Codex trata `model` e `model_reasoning_effort` em `config.toml` como defaults duráveis. A precedência relevante é: flags/overrides da CLI, `.codex/config.toml` do projeto confiável e `~/.codex/config.toml`. Portanto, o pin que bloqueia a preferência pessoal é o do projeto, porque ele prevalece sobre o global.
-
-Para permitir escolha manual em Conversation e Task-first, não fixe `model`, `model_reasoning_effort` nem `service_tier` no `.codex/config.toml` do projeto. O arquivo global pode guardar a última preferência escolhida manualmente pelo usuário; remova esses campos globais somente quando quiser voltar aos valores recomendados. Reinicie o Codex depois de uma edição externa e use `/debug-config` ou `codex --strict-config` quando houver dúvida sobre precedência.
-
-## Princípios de decisão
-
-1. **Qualidade é uma restrição, não uma média com custo.** Acceptance Criteria, testes e gates precisam passar antes de otimizar tokens.
-2. **Use o menor effort que entrega a qualidade necessária.** Aumente somente por necessidade observável ou ganho medido.
-3. **Modelo, effort e risco são dimensões diferentes.** O modelo segue a forma e a complexidade da Task; o agente fornece o effort-base; o risco define gates.
-4. **Validação reduz bugs melhor que effort isolado.** Testes determinísticos, revisão independente e auditoria não podem ser substituídos por mais reasoning.
-5. **Custo relevante é o total até a entrega verificada.** Planejamento barato que gera muitos reparos pode custar mais que um planejamento mais profundo.
-6. **Escalada exige evidência.** Ambiguidade, falha estrutural, finding ou rework justificam elevar um nível; volume mecânico não.
-7. **Toda decisão deve ser observável.** Registre a configuração planejada no Agent Run e, quando disponível, a configuração efetiva agregada de suas Calls.
+## Objetivo e versão do contrato
+
+A política busca resolver a entrega com prova suficiente e reduzir retrabalho,
+sem economia acima da qualidade nem persistência ilimitada por padrão.
+Este guia descreve as fontes em preparação para a v3, não uma release publicada.
+O [guia 19](19-assurance-e-autonomia.md) contém configuração, contagem e limites
+de `autonomy-v1`. A configuração efetiva do projeto e a versão instalada
+prevalecem sobre exemplos.
+
+Há três decisões independentes: modelo/esforço da invocação, persistência por
+Task e rigor da verificação. Risco não é quantidade de tentativas; preset de
+autonomia não é perfil de instalação nem permissão.
+
+## Principal avulso e delegação
+
+Conversation e principal de Task avulsa preservam o modelo e esforço escolhidos
+manualmente no Codex. Priorize execução direta. O ZAIP não troca silenciosamente
+o seletor do usuário nem exige subagente para responder uma pergunta simples.
+
+Se a entrega precisar de especialidade, isolamento ou revisão/finalização
+exigida, delegue pelo catálogo com escopo e responsabilidade explícitos. Antes,
+informe:
+
+> Orquestração ZAIP: subagentes podem usar modelo e esforço diferentes do agente
+> principal, conforme o perfil de autonomia. A configuração efetivamente
+> observada será informada.
+
+Não há obrigação de herdar o modelo do principal. Selecionar Astra/ultra no
+Codex não significa que todos os filhos executarão Astra/ultra. Modelo/effort
+planejados e efetivos são campos distintos; só a observação do host/provider
+comprova os efetivos. Reutilizar um UUID nativo não comprova que o modelo da
+nova invocação permaneceu igual.
+
+Delegação flexível não autoriza outro chat, identidade inventada, alteração de
+permissões, perda da revisão independente ou segundo responsável pela mesma
+Task. Delivery exige executor capturado ou contrato de raiz direta autorizada
+desde o início; a preferência direta não dispensa Evidence, revisão ou Gui.
+
+## Escalada em autonomy-v1
+
+| Preset | Replanejamento 1 | Replanejamento 2 | Replanejamento 3 | Execução Astra |
+| --- | --- | --- | --- | --- |
+| `essential` | Sol/high | Não existe | Não existe | Nunca automática |
+| `balanced` | Sol/high | Astra/high | Astra/high | Elegível no bloco do terceiro replanejamento |
+| `persistent` | Sol/high | Astra/high | Astra/high, e seguintes sem teto | Elegível a partir do terceiro replanejamento |
+
+O Essencial permite no máximo quatro execuções de produto e um
+replanejamento. O Equilibrado permite dez execuções e três replanejamentos.
+O Persistente é opt-in genuinamente ilimitado; não recebe o teto legado de
+três diagnósticos Astra. Cada plano válido libera até três reparações.
+
+A única exceção Astra no Essencial é o **principal avulso selecionado
+manualmente**. A seleção automática final é revalidada depois de herança,
+fallback e configuração. Um modelo Astra configurado num agente não libera
+Astra automático no Essencial.
+
+Nos demais presets, Astra automático usa somente `high`: não `xhigh`,
+`max` ou `ultra`. Pode replanejar a partir do segundo plano e executar a
+partir do terceiro, quando a rota válida o selecionar; não se torna reviewer
+ou finalizer. A exceção de execução não acrescenta tentativas nem amplia
+write scopes.
+
+O primeiro replanejamento usa `gpt-5.6-sol`; os seguintes permitidos usam
+`gpt-6-astra`. Executor e replanejador são invocações diferentes. Planejar
+com Astra não obriga a executar com Astra no segundo bloco.
+
+## Replanejar não é repetir sem diagnóstico
+
+O replanejador recebe objetivo, ACs, falha observada, evidência, restrições e
+histórico compacto do que foi tentado. O retorno gerenciado é JSON estrito com
+`hypothesis`, `test` e `executor_model`; a rota conserva o escopo autorizado.
+O adaptador isola suas ferramentas e MCPs; esse papel não
+edita produto nem cria outros filhos.
+
+No gerenciado, o pacote serializado é delimitado a 48.000 bytes e declara
+8.000 tokens de saída. Bytes não são tokens faturados. O modelo/esforço e a
+reserva são validados antes do despacho, e o resultado é persistido de forma
+imutável. Plano inválido consome a reserva e não libera reparação.
+
+Uma reparação aplica uma hipótese verificável, testa o comportamento relevante
+e preserva os ACs. Ausência de progresso exige diagnóstico novo dentro do
+orçamento; testes repetidos sem mudança não constituem nova evidência.
+Falha de ferramenta, credencial ou ambiente não comprova falha de raciocínio.
+
+Não existe abandono da Task por 15 ou 60 minutos. Timeouts técnicos, leases,
+telemetria de duração e checkpoints têm outras funções. Resultado desconhecido
+não libera despacho duplicado. Para retomada, consulte o diário existente,
+não crie outra Task ou apague `.local` para renovar a quota.
 
 ## Família de modelos
 
-A política preserva GPT-5.6 para execução e acrescenta Astra somente para diagnóstico difícil evidenciado:
-
-| Modelo | Uso preferencial |
-| --- | --- |
-| `gpt-5.6-luna` | trabalho claro, repetitivo, determinístico e de alto volume |
-| `gpt-5.6-terra` | implementação, teste, diagnóstico e integração cotidiana |
-| `gpt-5.6-sol` | trabalho ambíguo, transversal, arquitetural, crítico ou de alto valor |
-| `gpt-6-astra` | diagnóstico excepcional, somente `high`, seguido de devolução ao executor |
-
-Os defaults iniciais ficam definidos assim:
-
-| Campo | Default |
-| --- | --- |
-| modelo fallback/baseline | `gpt-5.6-terra` |
-| effort fallback/baseline | `medium` |
-| velocidade fallback/baseline | `standard` |
-| modelo eficiente elegível | `gpt-5.6-luna` |
-| modelo frontier elegível | `gpt-5.6-sol` |
-| consultor diagnóstico excepcional | `gpt-6-astra high`; até três diagnósticos por Task |
-| teto automático de effort | `xhigh` |
-| `xhigh` automático | habilitado somente pelos critérios de elegibilidade |
-| `max` e `Ultra` automáticos | fora de escopo |
-| velocidade solicitada | sempre `standard`; não participa da seleção |
-
-Terra `medium` é o fallback quando os sinais forem insuficientes ou conflitantes. Sol não deve ser usado em tudo; Luna não deve ser usado quando a Task depende de julgamento arquitetural ou ambiguidade relevante.
-
-`ultra` e `max` não fazem parte da política: o ZAIP-AIOS nunca os seleciona. Luna, Terra e Sol usam effort `low`, `medium`, `high` ou `xhigh` conforme elegibilidade. Astra usa somente `high`; nem um override libera `xhigh`, `max` ou `ultra` para ele.
-
-### Astra: diagnóstico, correção de rota e devolução
-
-Sol permanece como escolha normal da faixa difícil. Astra recebe uma questão diagnóstica delimitada quando o ganho potencial de evitar novo reparo justifica seu uso. A regra canônica é [RULE-ASTRA-DIAGNOSTIC](../../rules/astra-diagnostic.md), carregada apenas nessa avaliação; o kernel e os prompts de Marketing, Sales, Growth e Ops não incorporam essa expansão.
-
-| Situação observada | Rota |
-| --- | --- |
-| Pergunta direta, copy, análise comercial simples, alteração mecânica | Luna/Terra conforme perfil existente |
-| Arquitetura ou problema difícil com caminho conhecido | Sol; execução delimitada em Luna/Terra |
-| Tentativa executora falhou por hipótese/raciocínio; complexidade ou ambiguidade alta e evidência disponível | Um diagnóstico Astra high antes do reparo seguinte |
-| Impacto material crítico e diagnóstico difícil, ambos evidenciados | Astra high preventivamente, antes da primeira implementação |
-| Falha de ambiente, credencial, ferramenta, sintaxe ou ausência de prova | Corrigir a condição ou obter prova com o executor; não acionar Astra |
-| Mesmo diagnóstico/plano sem progresso, ou três diagnósticos já reservados | Parar a escalada; executar rota útil ou registrar bloqueio concreto |
-
-A expressão “tarefa crítica”, o risco isolado, o departamento, a quantidade de arquivos e o tamanho do pedido nunca bastam. A política usa metadados estruturados e prova referenciada. Um reparo localizado não se torna diagnóstico difícil só porque a primeira tentativa falhou.
-
-Cada ciclo significa **uma invocação diagnóstica Astra governada**, com reserva atômica antes do dispatch. O teto é três por ID estável de Task, somando retomadas, Runs e Executions; normalmente basta uma consulta. Uma reserva consumida não permite repetir o dispatch nem é devolvida após timeout. Call interna, evento de uso e checkpoint não são contadores de diagnóstico.
-
-O pacote de entrada contém falha observada, tentativa anterior, evidência, restrições e critérios de aceite. É uma sessão nova, sem herdar histórico integral, sem ferramentas de execução nem filhos. O envelope limita a entrada serializada a 48000 bytes, declara até 8000 tokens de saída e termina após até 180 segundos. Bytes não equivalem a tokens; o runtime verifica o consumo informado pelo provider, sem transformar orçamento declarado em economia medida.
-
-Astra retorna JSON com `findings`, `evidence`, `cause_or_hypothesis`, `route`, `scope`, `test_plan`, `executor` e `recommended_model` restrito a Luna/Terra/Sol. O coordenador valida o retorno e entrega a correção ao executor. Astra não implementa, não substitui a revisão normal e não finaliza a entrega.
-
-O objetivo da segunda tentativa é aplicar uma hipótese corrigida e testável. Outra consulta precisa de evidência nova e mudança de hipótese/rota; não se permite repetir o mesmo plano alternando Astra e Sol. Se faltar prova para avançar, o retorno identifica a prova faltante, sem prometer resolução automática.
-
-A política `model-orchestration-v2` mantém legível a configuração anterior com três modelos. Incluir Astra na allowlist habilita apenas essa rota condicionada; removê-lo desativa novos diagnósticos preservando histórico e quota. Novas instalações continuam em `manual`. O modo automático permanece restrito a SPEC/PRD. O framework controla processos que ele próprio despacha; não consegue alterar ou limitar uma sessão manual já selecionada no aplicativo Codex.
-
-O isolamento é aplicado pelo adapter Codex antes da inferência: configuração transitória, sandbox de leitura, ferramentas de shell/apps/browser/multi-agent desabilitadas e cada servidor MCP efetivo desabilitado individualmente. Se a configuração não puder ser verificada, o diagnóstico não inicia. Um evento inesperado de ferramenta provoca cancelamento adicional; essa verificação posterior não substitui a restrição anterior.
-
-## Reasoning effort
-
-| Effort | Uso recomendado |
-| --- | --- |
-| `low` | execução clara, roteamento, busca delimitada, transformação e integração sem conflito |
-| `medium` | padrão para agentic coding, planejamento delimitado, implementação e revisão cotidiana |
-| `high` | debugging complexo, planejamento profundo, síntese final e auditoria crítica delimitada |
-| `xhigh` | exceção para planejamento, replanejamento, segurança, code review ou auditoria em problemas excepcionalmente difíceis |
-
-Regras adicionais:
-
-- `xhigh` é aceito pelo framework automático, mas permanece inelegível para trabalho comum.
-- `xhigh` e `high` não devem ser defaults de implementação extensa.
-- `xhigh` pode ser selecionado automaticamente somente quando os critérios de elegibilidade forem satisfeitos; os evals devem calibrar os gatilhos sem liberar uso genérico.
-- `high` e `xhigh` devem receber contexto e saída delimitados para evitar turnos abertos e excessivamente longos.
-- `max` não pertence à primeira versão automática e `ultra` é explicitamente inválido no modo `auto`.
-
-## Velocidade por origem
-
-Modelo e effort podem variar entre Agent Runs, nunca entre Calls da mesma Run. A origem da Execution define quem controla a velocidade:
-
-| Origem | Modelo e effort | Velocidade | Execução Fast |
-| --- | --- | --- | --- |
-| Conversation | seleção manual do Codex | seleção manual do Codex | não é execução de produto |
-| Task-first | seleção manual do Codex | seleção manual do Codex | somente por seleção manual no Codex |
-| SPEC | política automática ZAIP | sempre `standard` | não suportada |
-| PRD | política automática ZAIP | sempre `standard` | não suportada |
-
-No modo `auto`, toda Run de PRD ou SPEC solicita velocidade `standard`, e nenhum override de Task, PreparedPlan ou Execution pode mudá-la durante sua vigência. Tasks descendentes não podem escapar dessa regra. O `service_tier` efetivo retornado pelo host/provider continua sendo registrado como observação, mas não altera `default_velocity` nem retroalimenta o seletor.
-
-Selecionar Fast manualmente no Codex afeta somente Conversation ou Task-first, conforme o estado do host. O ZAIP não muda o seletor, não grava Fast em configuração persistente e não propaga a seleção para uma futura Execution de PRD ou SPEC. Se um trabalho urgente exige a DAG ou os gates parentais de uma SPEC/PRD, ele continua em `standard`; não fragmente artificialmente o macro em Task-first apenas para obter mais velocidade.
-
-## Separação entre risco e complexidade
-
-O ZAIP usa duas classificações independentes:
-
-- risco: `lite`, `standard`, `critical`;
-- complexidade: `simple`, `standard`, `complex`.
-
-O risco governa verificação e proteção. A complexidade influencia modelo e effort.
-
-| Risco | Gates mínimos esperados |
+| Modelo | Papel dentro da política ZAIP |
 | --- | --- |
-| `lite` | verificação scoped e Acceptance Criteria aplicáveis |
-| `standard` | testes dos packages afetados, revisão e evidência |
-| `critical` | verificação completa, revisão independente, segurança quando aplicável, rollout e rollback |
-
-Uma Task `critical` e mecânica pode ser executada em Terra `medium`, desde que receba gates críticos. Uma Task de risco `standard`, mas altamente ambígua e transversal, pode exigir Sol `medium` ou `high` no planejamento.
+| `gpt-5.6-luna` | Execução clara e delimitada, conforme catálogo e capacidade |
+| `gpt-5.6-terra` | Implementação, testes e integração cotidianos |
+| `gpt-5.6-sol` | Planejamento difícil, revisão especializada e primeiro replanejamento |
+| `gpt-6-astra` | Replanejamentos e exceção de execução permitidos pelo preset |
 
-## Política por agente
+Esses são papéis configurados pelo ZAIP, não alegações de benchmark dos
+modelos. Disponibilidade e esforços aceitos precisam ser confirmados no host.
+Mais reasoning não substitui teste, reviewer ou evidência.
 
-O agente define um baseline, nunca a decisão inteira. A política combina papel, fase e metadados da Task quando o Agent Run começa:
+O catálogo define baselines por agente. Uma seleção deliberadamente diferente
+abre nova Run com sua identidade real. Calls internas preservam a configuração
+solicitada da Run; fallback do provider aparece como observado, sem reescrever
+o cabeçalho. Sem fonte efetiva, mantenha `null`/`unavailable`.
 
-O catálogo mantém IDs internos estáveis como `agent-builder`, enquanto o adapter Codex os registra como `zaip-agent-builder`. O nome exibido vem de `codex_task_name` e coincide com o único `nickname_candidates`: `nome_funcao_por_extenso_zaip_agent`, sem repetir o cargo técnico. O adapter configura `max_depth = 2` e `max_concurrent_threads_per_session = 5`: essa é capacidade estrutural da squad, não permissão para executar cinco Tasks. A execução autônoma começa com uma Task e só eleva até três ramos realmente independentes.
+## Configuração e ativação
 
-| Agente | Configuração-base | Elevação típica |
-| --- | --- | --- |
-| `agent-orchestrator` | Terra `low` | Sol `medium` para DAG complexa; `high` para síntese final crítica |
-| `agent-builder` | Terra `medium` | Sol `medium` para arquitetura, segurança ou migração |
-| `agent-reviewer` | Terra `medium` no catálogo | Sol quando a política e os sinais da revisão justificarem elevação; `high` para revisão complexa delimitada |
-| `agent-integrator` | Terra `medium` | Sol `medium` somente quando outra regra explícita exigir raciocínio transversal |
-| `agent-auditor` e `agent-security-auditor` | Sol `high` | `xhigh` apenas quando elegível e medido |
-| `agent-finalizer` | Terra `medium` | sem elevação automática; avalia evidência já produzida |
-| fallback `codex` | Terra `medium` | resolver novamente pela Task e pelos gates |
-
-Se nenhum agente do catálogo for selecionado, o nome do cliente/host é usado como fallback de identidade. No Codex:
+Mescle na raiz de `.agents/config/project.yaml`:
 
 ```yaml
-agent: codex
-client: codex
-provider: openai
+autonomy:
+  version: 1
+  preset: balanced
+execution:
+  runtime: manual
 ```
 
-`agent`, `client` e provider de inferência são dimensões diferentes. O fallback de agente continua `codex`; a inferência dos modelos GPT-5.6 usa provider `openai`. Identidade do agente e configuração do modelo são decisões separadas.
-
-## PRD e SPEC
-
-### PRD
-
-Use `medium` para descoberta e primeiro rascunho. Use `high` quando o PRD tiver múltiplos stakeholders, trade-offs relevantes ou várias SPECs. Reserve `xhigh` para uma passagem final em PRDs críticos que governem múltiplas SPECs, decisões de alto custo de reversão, compliance, segurança ou rollout complexo.
-
-### SPEC
-
-A SPEC tem maior potencial de retorno para reasoning elevado porque seus erros se propagam para DAG, Tasks e implementação. Use `high` em SPECs transversais ou arquiteturais. Uma passagem final `xhigh` pode ser elegível quando houver:
+Esse exemplo configura o preset **sem iniciar provider**. Novos templates
+também mantêm seleção `model_orchestration.mode: manual`. O coordenador
+gerenciado usa `execution.runtime: managed` para PRD/SPEC (padrão novo), ou
+`autonomous` também para Task gerenciada explícita, provider/configuração
+válidos, execução autorizada e worktree elegível. Salvar o preset no Dashboard
+não faz essa ativação automaticamente.
+
+O bloco `autonomy` aceita somente `version` e `preset`. As sequências
+4/1, 10/3 e ilimitada vêm da política compartilhada, não de um campo de
+tentativas inventado no YAML. As Tasks iniciadas congelam a política; alteração
+no projeto vale para novas Tasks. Estados legados não são convertidos
+silenciosamente.
+
+A allowlist e as capacidades do provider continuam sendo verificadas.
+Não remova uma restrição para fazer uma seleção impossível parecer válida.
+No caminho gerenciado, o worker não pode contornar o orçamento iniciando
+filhos nativos não contabilizados via `multi_agent`.
+
+## Fronteira de garantia
+
+O runtime gerenciado controla o processo **antes** da inferência. Essa é a
+fronteira da contagem determinística e da seleção automática. Uma chamada
+nativa `spawn_agent` externa, feita diretamente pelo Codex, não é interceptada
+pelo diário: instrução e captura posterior não equivalem a controle preventivo.
+
+O padrão novo `managed` já seleciona PRD/SPEC gerenciados, sem prometer
+controle externo numa sessão manual. `task migrate-autonomy` exige preview,
+contagem histórica revisada e confirmação; não reinicia quotas ou aprova legados.
+
+A preferência do principal avulso, o catálogo gerado do filho e a configuração
+efetivamente observada devem aparecer separados. Se o host não suporta o
+override necessário, relate a limitação real; não afirme que um prompt mudou
+o modelo e não fabrique telemetria.
+
+## Compatibilidade: model_orchestration sem autonomy
+
+Configurações antigas mantêm o contrato legado, não os presets acima:
+
+- `manual` recomenda sem alterar o seletor; `off` desativa essa recomendação.
+- `auto` usa `automatic_sources: [spec, prd]`; `task` não é aceito nessa
+  allowlist legada. Isso não proíbe a política de filhos avulsos de
+  `autonomy-v1`.
+- Sinais persistidos de complexidade, ambiguidade, transversalidade, rework,
+  risco e papel definem o perfil e motivos. Quantidade de arquivos ou
+  departamento não substitui esses sinais.
+- Luna/Terra/Sol usam esforços permitidos pelo projeto; `xhigh` é
+  excepcional para planejamento/auditoria difícil, não um padrão para tudo.
+- Astra legado é diagnóstico read-only condicionado e limitado a três
+  invocações por Task estável. Esse teto **não se aplica** ao Persistente.
+- Overrides e allowlist legados não se sobrepõem às restrições de
+  `autonomy-v1`, em especial à proibição de Astra automático no Essencial.
+
+Consulte [RULE-ASTRA-DIAGNOSTIC](../../rules/astra-diagnostic.md),
+[RULE-AUTONOMY-DECISION](../../rules/autonomy-decision.md) e
+[RULE-MODEL-ORCHESTRATION](../../rules/model-orchestration.md), apenas quando
+aplicáveis. Não carregue o diagnóstico difícil para uma pergunta comercial
+simples.
 
-- frontend, backend e persistência ou infraestrutura;
-- mudança de contrato de API;
-- múltiplos módulos dependentes;
-- migração e compatibilidade temporária;
-- autenticação, autorização, segurança ou dados críticos;
-- rollout e rollback complexos;
-- muitas Tasks paralelas ou locks relevantes;
-- rework anterior causado por falha de arquitetura;
-- Acceptance Criteria difíceis de transformar em testes.
-
-### Fluxo econômico de planejamento
-
-```text
-Descoberta e rascunho       -> Terra ou Sol medium
-Estruturação do PRD/SPEC    -> Sol high, quando complexo
-Crítica e consolidação final -> Sol xhigh, somente quando elegível
-Execução da DAG             -> Luna low ou Terra medium
-Auditoria final             -> Sol medium ou high
-```
-
-O melhor uso de `xhigh` é como crítico final de um documento já estruturado, não como autor a partir de uma página em branco. O turno deve receber Requirements, Acceptance Criteria, decisões, restrições, contratos, riscos, testes, rollout e rollback. A saída deve ficar limitada a contradições, lacunas, riscos, correções e decisão de prontidão.
-
-## DAG e múltiplas Tasks
-
-O resolvedor executa antes de cada Task pronta e novamente quando uma etapa materialmente distinta abre outro Agent Run:
-
-```text
-Task pronta
--> resolver agente
--> resolver modelo e effort
--> validar capacidades do modelo
--> iniciar Agent Run
--> registrar configuração solicitada
--> executar e verificar
--> registrar configuração efetiva
-```
-
-Se Tasks paralelas exigirem configurações diferentes, cada uma deve usar Agent Run isolada. Em uma mesma thread sequencial, cada nova Run recebe explicitamente modelo e effort para impedir herança acidental da configuração anterior.
-
-Para PRDs, o runtime materializa Executions-filhas somente quando as dependências permanecem dentro da SPEC e os write scopes são globalmente disjuntos. Cada filha recebe Agent Runs, estado, orçamento e handoff próprios. O pai aguarda os terminais, integra os commits sem reexecutar Tasks e aplica validação cross-SPEC antes do finalizer; ramos inelegíveis permanecem em sua DAG global.
-
-## Rework e escalada
-
-Comece na configuração mais barata considerada segura:
-
-```text
-Luna low -> Terra medium -> Sol medium -> Sol high -> Sol xhigh
-```
-
-Eleve apenas um nível por vez, em novo turno, quando houver:
-
-- ambiguidade material não resolvida;
-- falha de teste após tentativa válida de correção;
-- conflito arquitetural ou entre módulos;
-- finding de segurança;
-- rejeição do reviewer;
-- invalidação do PreparedPlan por aumento de complexidade;
-- evidência insuficiente para Acceptance Criteria;
-- rework estrutural causado por dependência, contrato, sequência, migração ou escopo.
-
-Não eleve por erro de sintaxe, teste localizado, código gerado, refatoração repetitiva ou simples quantidade de arquivos.
-
-### Elegibilidade para xhigh
-
-Exija as quatro condições:
-
-1. alta complexidade ou ambiguidade arquitetural;
-2. alto custo esperado de rework;
-3. efeito transversal ou crítico;
-4. turno delimitado de planejamento, replanejamento ou auditoria.
-
-Além disso, exija pelo menos dois gatilhos observáveis:
-
-- frontend, backend e persistência ou infraestrutura;
-- três ou mais módulos com contratos compartilhados;
-- migração, segurança, autenticação ou dados críticos;
-- rollout parcial e rollback necessário;
-- dois ciclos de reparo falharam pela mesma causa estrutural;
-- finding arquitetural do reviewer;
-- PreparedPlan invalidado;
-- alternativas arquiteturais com trade-offs materiais.
-
-Os números são critérios operacionais iniciais do ZAIP, não limites publicados pela OpenAI. Eles devem ser recalibrados por evals.
-
-## Medição e break-even
-
-O KPI principal é `tokens totais até entrega verificada`:
-
-```text
-custo total = planejamento
-            + implementação
-            + testes e diagnóstico
-            + revisão e auditoria
-            + ciclos de reparo
-```
-
-O break-even de `xhigh` é:
-
-```text
-custo adicional do planejamento xhigh / custo médio de um ciclo de rework
-```
-
-Se `xhigh` adicionar `E` tokens ao planejamento e um ciclo médio de rework custar `R`, ele precisa evitar ao menos `E / R` ciclos por Task para empatar em tokens. Latência, custo monetário e criticidade continuam como guardrails separados.
-
-### Métricas obrigatórias
-
-- sucesso da Task e dos Acceptance Criteria;
-- tokens totais e tokens de reasoning;
-- latência total até conclusão;
-- custo total até entrega verificada;
-- aprovação na primeira revisão;
-- quantidade de repair cycles;
-- findings arquiteturais e de segurança;
-- falhas de integração;
-- invalidações do PreparedPlan;
-- completude das evidências;
-- bugs encontrados depois da entrega.
-
-### Piloto recomendado
-
-Compare `Sol high` e `Sol xhigh` somente no planejamento, mantendo execução e revisão iguais:
-
-```text
-Grupo A: planejamento Sol high  -> execução Terra medium -> revisão Sol medium
-Grupo B: planejamento Sol xhigh -> execução Terra medium -> revisão Sol medium
-```
-
-Ative `xhigh` para uma classe de trabalho somente quando o grupo correspondente demonstrar ganho de qualidade ou confiabilidade que compense tokens, custo e latência adicionais.
-
-## Contrato de configuração automática
-
-A configuração automática usada pelo projeto é:
-
-```yaml
-model_orchestration:
-  mode: auto
-  default_model: gpt-5.6-terra
-  default_effort: medium
-  default_velocity: standard
-  allowed_models:
-    - gpt-5.6-luna
-    - gpt-5.6-terra
-    - gpt-5.6-sol
-  allowed_efforts:
-    - low
-    - medium
-    - high
-    - xhigh
-  max_auto_effort: xhigh
-  automatic_sources:
-    - spec
-    - prd
-  notice: mismatch
-```
-
-Projetos novos continuam em `manual` até o rollout provar qualidade e custo. A mudança para `auto` é opt-in por projeto e por origem; `task` é rejeitado pelo schema. Rollback consiste em voltar para `manual`, sem reescrever Runs anteriores.
-
-Um novo PreparedPlan de PRD/SPEC não declara apenas `risk: standard`. Cada blueprint fornece `model_signals`, e `createPreparedPlanV2` calcula e persiste `model_profile.risk`, `risk_policy_version: task-risk-v1` e `risk_reasons`. Uma declaração de risco conflitante falha; PreparedPlans históricos sem perfil continuam legíveis, mas não entram em execução automática sem perfil.
-
-```yaml
-model_signals:
-  phase: implementation
-  complexity: complex
-  transversality: cross_system
-  ambiguity: high
-  rework: none
-  rework_cost: high
-  bounded: true
-  high_volume: false
-  xhigh_triggers:
-    - shared_contracts_3_plus
-    - rollout_and_rollback
-  risk_signals:
-    production_impact: false
-    external_action: false
-    irreversible_change: false
-    security_or_critical_data: true
-    data_migration: false
-    broad_audit: false
-    rollback: planned
-    verification_scope: full
-```
-
-O classificador retorna `critical` para impacto explícito em produção, ação externa, irreversibilidade, segurança/dados críticos, migração, auditoria ampla, rollback complexo, ambiguidade `high` transversal ou rework estrutural de alto custo. Retorna `lite` somente para trabalho simples, local, delimitado, reversível e com verificação scoped; todo caso restante é `standard`, sempre com motivo enumerado.
-
-O PreparedPlan pode declarar um override da Execution e cada Task pode sobrescrever campos:
-
-```yaml
-policy:
-  runtime_defaults:
-    client: codex
-    provider: openai
-    model: gpt-5.6-terra
-    reasoning_effort: medium
-
-blueprints:
-  tasks:
-    - id: TASK-IMPLEMENTAR
-      runtime:
-        model: gpt-5.6-terra
-        reasoning_effort: medium
-
-    - id: TASK-AUDITAR
-      runtime:
-        model: gpt-5.6-sol
-        reasoning_effort: high
-```
-
-Precedência executada:
-
-```text
-policy.runtime_defaults explícito da Execution
--> runtime explícito da Task
--> política automática por perfil, fase e agente
--> defaults do projeto
-```
-
-O runtime anuncia modelos, efforts e velocidades antes do dispatch. Modelo fora da allowlist, effort desconhecido, `ultra`, `max`, velocidade diferente de `standard` ou capacidade incompatível produzem erro tipado; não existe fallback silencioso.
-
-Quando a seleção foi registrada, o cabeçalho da Run ou Sub-Run preserva a configuração resolvida e `model.selection.recorded` registra a decisão antes do dispatch; o default do catálogo não pode substituir o modelo realmente invocado. Telemetria efetiva e Calls conhecidas permanecem dentro da mesma chamada de agente. Capturas terminais sem metadados ricos mantêm modelo e effort indisponíveis; não devem receber uma seleção reconstruída. Run raiz é a chamada do orquestrador e possui `parent_run_id: null`; Sub-Run possui pai:
-
-```yaml
-agent_run:
-  run_id: RUN-EXEC-TASK-BUILD-1
-  run_kind: sub_run
-  run_purpose: execution
-  parent_run_id: RUN-EXEC-TASK-ORCHESTRATOR
-  client: codex
-  provider: openai
-  agent: agent-task-executor
-  agent_name: zaip-agent-task-executor
-  requested_model: gpt-5.6-terra
-  requested_reasoning_effort: medium
-  effective_model: gpt-5.6-terra
-  effective_reasoning_effort: medium
-  call_count: 3
-  tokens: 42000
-  cost_brl: 1.84
-  selection_source: execution-override
-  selection_reasons:
-    - execution-override
-    - terra-implementation-baseline
-```
-
-Requested e effective não devem ser confundidos, pois o runtime ou serviço pode aplicar fallback ou reroteamento. `effective_*` só pode ser preenchido por fonte observada; ausência dessa fonte não autoriza copiar `requested_*`.
-
-No dashboard, Runs e Sub-Runs são separados por `parent_run_id` e ordenados por `started_at` decrescente, independentemente do shard físico da projeção. A Run raiz usa a identidade visível `zaip-agent-orchestrator`; Sub-Runs usam o `zaip-agent-*` efetivamente selecionado. O Monitor de Custos agrupa e filtra pela identidade visível, mantém o modelo configurado de cada chamada em destaque e mostra o modelo efetivo separadamente. Quando o host não informou a configuração planejada, o modelo efetivo é rotulado como observado, nunca apresentado como se tivesse sido selecionado pelo catálogo.
-
-### Calls como telemetria interna
-
-O dashboard cria visões separadas para Runs e Sub-Runs, mas não cria entidade ou aba separada para Calls. Quando o host fornece eventos por `invocation_id`, o ledger os conserva dentro da respectiva Run/Sub-Run para calcular:
-
-1. quantidade de Calls conhecida e quantidade terminal;
-2. falhas, cancelamentos, retries e latência observáveis;
-3. modelo, effort e service tier efetivos;
-4. tokens e custo agregados na Run;
-5. divergência requested/effective sem dupla contagem.
+## Velocidade por origem
 
-Todas as Calls da mesma Run reutilizam a configuração planejada. Se o provider aplicar fallback, a diferença aparece como configuração efetiva observada e não muda o cabeçalho. Valores indisponíveis permanecem `null`; prompt e reasoning privado nunca são armazenados.
+A seleção automática solicita `standard`. Fast manual de uma Conversation ou
+Task avulsa independente pertence ao host; o ZAIP não o ativa nem propaga
+para o runtime automático de SPEC/PRD. Não fragmente uma DAG para fugir de sua
+política. O tier efetivamente retornado é observação separada, não prova de
+que o catálogo ou o preset o selecionou.
 
-## Garantias implementadas
+## Medir resultado, sem prometer economia
 
-1. `project.yaml` possui branch `auto` estrito e mantém `manual` como default de distribuição.
-2. `automatic_sources` restringe a política a `spec` e `prd`; o schema rejeita `task`.
-3. Novos PreparedPlans de PRD/SPEC calculam risco e motivos a partir de sinais persistidos; planos históricos permanecem legíveis.
-4. O coordenador injeta a política somente em Executions elegíveis e resolve novamente no início de cada Agent Run de Task/fase.
-5. A captura de conversa registra o modelo explicitamente observado ou `unknown`; modelo e effort efetivos não são inferidos a partir do baseline automático, do catálogo ou de uma Task avulsa.
-6. O resolvedor determinístico aplica allowlist, capacidades, overrides e motivos observáveis antes do dispatch.
-7. Testes cobrem a matriz de risco/modelo/effort, precedência, capacidades, rejeições e atribuição sem inferência.
-8. O ledger rejeita Calls com modelo, effort ou decisão de seleção solicitados diferentes dentro da mesma Agent Run.
-9. O Sub-Run registra no cabeçalho e no ledger a seleção realmente enviada ao runtime.
-10. CLI, Rules, adapters e templates distribuídos descrevem a mesma fronteira.
+Compare Tasks equivalentes com os mesmos ACs e qualidade mínima, somando
+planejamento, implementação, reparos, testes e revisão. Inclua cobertura,
+configurações observadas e falhas; não compare só o preço do primeiro turno.
 
-## Não objetivos da primeira automação
+Tokens, tempo e custo continuam úteis para diagnóstico. Nenhum deles vira
+teto de abandono por tempo em `autonomy-v1`. Custo equivalente de API não é
+cobrança comprovada da assinatura. `null` não é zero e teste com runtime
+simulado não comprova economia real.
 
-- aceitar `ultra` no modo automático;
-- usar `max` como default;
-- selecionar ou sobrescrever velocidade diferente de `standard`;
-- mudar modelo ou effort dentro de uma Agent Run;
-- criar uma tela ou lifecycle independente para Calls;
-- escolher `high` ou `xhigh` apenas por quantidade de arquivos;
-- substituir testes, reviewer ou auditor por reasoning mais alto;
-- inferir configuração ausente pelo comportamento do modelo;
-- otimizar somente o custo do primeiro turno e ignorar rework.
+## Fontes executáveis para manutenção
 
-## Referências oficiais
+No repositório-fonte:
 
-- [GPT-5.6: seleção de modelo e effort](https://developers.openai.com/api/docs/guides/latest-model#update-api-and-model-parameters)
-- [Reasoning effort](https://developers.openai.com/api/docs/guides/reasoning#reasoning-effort)
-- [Modelos do Codex](https://learn.chatgpt.com/docs/models#pick-a-reasoning-effort)
-- [Codex App Server](https://learn.chatgpt.com/docs/app-server)
-- [Subagentes: escolha automática de modelos e reasoning](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning)
-- [Configuração e precedência do Codex](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)
-- [Checklist de deployment e comparação por custo por sucesso](https://developers.openai.com/api/docs/guides/deployment-checklist#choose-a-gpt-56-model)
+- `packages/core/src/autonomy-policy.ts`: presets, modelos e divulgação.
+- `packages/core/src/autonomy-recovery.ts`: reservas, contagens e resultados.
+- `packages/tasks/src/autonomous/recovery-ledger.ts`: diário persistente.
+- `packages/tasks/src/autonomous/coordinator-autonomy.ts`: replanejamento.
+- `packages/tasks/src/autonomous/coordinator-autonomy-selection.ts`: seleção.
+- `packages/adapters/src/agent-runtime/autonomy-envelope.ts`: isolamento.
+- `AutonomySettings.tsx` no frontend do Dashboard: UI dos mesmos presets.
 
-As referências oficiais orientam usar o menor effort que atinja a qualidade necessária, começar em `medium` para equilíbrio e reservar `high` ou `xhigh` para ganho de qualidade medido. A política operacional deste guia deve continuar sendo validada pela telemetria e pelos evals do ZAIP.
+Esses paths são referências de mantenedor, não dependências que o consumidor
+precise compilar. Validação local, TGZ exato, revisão, fechamento canônico e
+produção são provas distintas; veja [qualidade e release](26-qualidade-e-release.md).