@zaip-ai/cli 1.0.8 → 1.3.1

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

@@ -0,0 +1,483 @@
+# 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.
+
+Toda Execution originada por PRD ou SPEC solicita velocidade `standard`, sem exceção ou override para Fast. A única forma suportada de executar trabalho de produto mais rápido é iniciar uma Task-first realmente independente e selecionar Fast manualmente no Codex; o ZAIP não ativa, persiste nem herda essa velocidade.
+
+## 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.
+
+## Família de modelos
+
+A política automática deve permanecer inicialmente na família GPT-5.6:
+
+| 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 |
+
+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` |
+| 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. A seleção usa somente Luna, Terra ou Sol com effort `low`, `medium`, `high` ou `xhigh`.
+
+## 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 |
+| --- | --- |
+| `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.
+
+## Política por agente
+
+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 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.
+
+| 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:
+
+```yaml
+agent: codex
+client: codex
+provider: openai
+```
+
+`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:
+
+- 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.
+
+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.
+
+## Garantias implementadas
+
+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.
+
+## Não objetivos da primeira automação
+
+- 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.
+
+## Referências oficiais
+
+- [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)
+
+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.

package/templates/.agents/zaip-aios/guides/24-calculo-de-custos-openai.md

@@ -0,0 +1,85 @@
+# Auditoria do cálculo de custo equivalente via API
+
+Este documento usa o snapshot versionado em `.agents/config/pricing/models.json`; não declara que as tarifas ou a cotação de exemplo são atuais fora desse snapshot.
+
+## Objetivo e limite
+
+O Monitor de Custos estima quanto as **mesmas métricas de uso observadas** custariam na OpenAI API. Não é uma fatura, não mede o consumo da assinatura ChatGPT/Codex e não pode ser usado para reconciliar créditos sem dados de billing mode e rate card aplicáveis.
+
+## Separação obrigatória
+
+| Sistema | Unidade | Pode virar USD? | Regra usada no Monitor |
+| --- | --- | --- | --- |
+| Codex autenticado com ChatGPT | créditos/limites | Não automaticamente | Tokens são preservados; não se infere cobrança da assinatura. |
+| OpenAI API | USD por milhão de tokens | Sim | Estimativa equivalente com o catálogo versionado. |
+
+O Fast do Codex é consumo de créditos da assinatura e não prova que uma requisição API foi atendida em Priority. Para esta estimativa equivalente, porém, uma Run marcada Fast usa a tarifa API Priority como **cenário hipotético para reproduzir a velocidade**, sem multiplicar tokens e sem ser apresentada como cobrança API efetiva.
+
+## Invariantes de telemetria
+
+O Monitor de Custos preserva a disponibilidade por métrica. Custo equivalente só é calculado quando os tokens, a identidade de preço e a tarifa necessária estão disponíveis. Lifecycle e telemetria parcial continuam visíveis com lacunas explícitas. `null` permanece `Indisponível`; nunca é convertido em zero. A projeção pode mostrar duração reconciliada, inferida ou estimada com proveniência, mas isso não é duração observada nem comprova uma medição da chamada.
+
+```text
+cached_input <= input
+reasoning <= output
+total = input + output
+```
+
+Cache é parte do input; reasoning é parte do output. Ambos são campos analíticos e nunca entram uma segunda vez no total ou no custo.
+
+## Fórmula API
+
+Para uma Run com tarifas resolvidas, em USD por 1M tokens:
+
+```text
+input_sem_cache = input - cached_input
+USD_input = input_sem_cache / 1_000_000 × tarifa_input
+USD_cache = cached_input / 1_000_000 × tarifa_cache
+USD_output = output / 1_000_000 × tarifa_output
+USD_total = USD_input + USD_cache + USD_output
+BRL_total = USD_total × cotação_USD_BRL
+```
+
+A conversão para BRL é a última etapa. Quando a moeda exibida é USD, não há conversão.
+
+## Exemplo didático — GPT-5.6 Sol, Standard
+
+No snapshot local consultado durante a redação, `gpt-5.6-sol` contém input US$5, cache US$0,50 e output US$30 por 1M. Esses números ilustram a fórmula; confira o catálogo e a fonte registrada antes de usar valores em uma decisão atual. Para 1.000.000 input, 800.000 cache, 100.000 output e 70.000 reasoning:
+
+```text
+input sem cache = 1.000.000 - 800.000 = 200.000
+input = 0,2 × 5,00 = US$ 1,00
+cache = 0,8 × 0,50 = US$ 0,40
+output = 0,1 × 30,00 = US$ 3,00
+reasoning = US$ 0,00 adicional (já está nos 100.000 output)
+total = US$ 4,40
+```
+
+Com uma cotação **hipotética** USD/BRL de 5,45: `4,40 × 5,45 = R$ 23,98`.
+
+## Service tier, contexto e dados incompletos
+
+- `priority` seleciona a tabela Priority oficial do modelo; não multiplica tokens. `fast` do Codex também seleciona essa tabela somente como cenário equivalente e deve ser rotulado como derivado de Fast.
+- Priority e contexto longo sem tarifa oficial combinada retornam custo indisponível, em vez de uma multiplicação inventada.
+- Regras de contexto longo só são usadas para modelos cujo catálogo traz limiar e tarifas publicadas.
+- Modelo sem correspondência, provedor incompatível ou tarifa ausente retorna `null` para custo.
+- Runs históricas sem billing mode, snapshot ou tier efetivo não comprovam uma cobrança; se faltarem os componentes exigidos pelo cálculo, o custo equivalente permanece indisponível.
+
+## Auditoria por Run
+
+Na aba Runs, confirme nesta ordem: fonte do modelo efetivo, velocidade observada, **Cenário velocidade API**, input, cache, output, reasoning, tarifas selecionadas, USD e BRL. Modelo/effort sem fonte observada permanecem indisponíveis. `Priority (derivado de Fast)` significa cenário de estimativa, não cobrança API comprovada. `USD/BRL registrado` e `BRL registrado` são fotografia histórica quando existirem; uma estimativa em BRL deve identificar a cotação usada, sem apresentá-la como valor atual por padrão.
+
+## Prova real agregada por modelo
+
+A aba **Modelos** não lista Runs. Cada linha agrega todas as Runs do modelo dentro dos filtros ativos. Ela soma input, cache, entrada sem cache, output, reasoning, output visível, total de tokens e cada componente em USD, inclusive `USD Standard`, acréscimo de velocidade, estimativa e valores registrados.
+
+As tarifas exibidas ali são **efetivas ponderadas**, não uma média simples: `USD do componente × 1.000.000 / tokens cobráveis do componente`. Assim, a taxa reproduz exatamente o custo agregado mesmo quando o modelo tiver Runs com contextos ou tarifas diferentes. Contexto, multiplicador de velocidade e cenário mostram `Misto` quando não forem uniformes; o dashboard não inventa uma média para multiplicadores.
+
+Para conferir a soma: `USD estimado API = USD entrada + USD cache + USD saída + USD raciocínio`; no snapshot local usado pela implementação, reasoning é parte de output e o componente adicional é zero quando `reasoning_billed_separately` é falso. O câmbio efetivo é `BRL estimado / USD estimado`, calculado somente depois da soma em USD.
+
+## Implementação e testes
+
+- Catálogo: `.agents/config/pricing/models.json`
+- Cálculo: `packages/costs/src/pricing-math.ts` e `packages/costs/src/index.ts`
+- Projeção: `.agents/dashboard/modules/cost-monitor/src/server/build-cost-monitor-projection.ts`
+- Testes: `pnpm --filter @zaip-ai/costs test` e `pnpm --filter @zaip-ai/dashboard-cost-monitor test`

package/templates/.agents/zaip-aios/guides/25-fontes-de-precos-openai.md

@@ -0,0 +1,19 @@
+# Fontes oficiais de preços OpenAI
+
+Registro local de consulta em 15 de julho de 2026. Valores operacionais ficam no catálogo versionado `.agents/config/pricing/models.json`; esta página preserva as fontes usadas naquele registro, não confirma preços atuais sem nova consulta.
+
+| Tema | Fonte oficial | Uso na implementação |
+| --- | --- | --- |
+| Tarifas API Standard, Batch, Flex e Priority | https://developers.openai.com/api/docs/pricing | Seleção de tarifa por modelo e `service_tier` efetivo. |
+| Créditos Codex por input, cache e output | https://learn.chatgpt.com/docs/pricing#what-are-tokens-and-credits | Referência separada; não é convertida automaticamente para USD. |
+| Velocidade do Codex | https://learn.chatgpt.com/docs/agent-configuration/speed | Fast é uma regra de créditos Codex; no Monitor ele pode alimentar o cenário API Priority, explicitamente como hipótese de equivalência de velocidade. |
+| Referência Responses | https://developers.openai.com/api/reference/resources/responses/methods/create | `service_tier` retornado representa o modo que efetivamente atendeu a requisição. |
+
+## Regras de atualização
+
+1. Consulte novamente a fonte oficial e registre a data/hora da nova consulta; não promova esta tabela histórica a estado atual.
+2. Atualize o catálogo em uma alteração separada e registre o snapshot/versão quando disponível.
+3. Inclua testes com input, cached input e output.
+4. Não crie tarifa para uma combinação que a tabela oficial não publique.
+5. Não transforme créditos Codex em USD sem uma regra oficial explícita.
+6. Preserve modelo, tier e effort efetivos como indisponíveis quando não forem retornados por fonte observada; defaults de configuração não os substituem.