@zaip-ai/cli 3.8.0 → 4.0.0

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

@@ -4,7 +4,8 @@
 
 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.
+Este guia distingue o comportamento distribuído da política aprovada para a
+v4. A revisão documental não é release nem prova do despacho Codex-native.
 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.
@@ -15,13 +16,16 @@ 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.
+Conversation sem ação preserva o modelo e esforço escolhidos manualmente no
+Codex e responde sem subagente. Para Task avulsa, a v4 exige subagentes
+nativos: o principal coordena, e o ZAIP escolhe modelo/effort de cada filho
+por papel, fase, criticidade e preset congelado. Não paralelize Tasks avulsas.
+O ZAIP não altera silenciosamente o seletor do principal do usuário.
 
-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:
+Para cada Task avulsa no contrato-alvo v4, delegue pelo catálogo nativo com
+escopo e responsabilidade explícitos. Especialidade, isolamento e
+revisão/finalização exigida determinam quais papéis adicionais são necessários.
+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
@@ -43,8 +47,8 @@ desde o início; a preferência direta não dispensa Evidence, revisão ou Gui.
 | 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 |
+| `balanced` (alvo v4) | Sol/high | Sol/high | Astra/high | Elegível no bloco do terceiro replanejamento |
+| `persistent` (alvo v4) | Sol/high | Sol/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.
@@ -57,14 +61,14 @@ 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
+`max` ou `ultra`. Na v4 só pode replanejar a partir do terceiro 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-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.
+Os dois primeiros replanejamentos usam `gpt-6-sol`; o terceiro e os
+seguintes permitidos usam `gpt-6-astra`. Executor e replanejador são
+invocações diferentes. Um plano Astra não obriga o executor a usar Astra.
 
 ## Replanejar não é repetir sem diagnóstico
 
@@ -118,9 +122,9 @@ execution:
   runtime: manual
 ```
 
-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
+Esse exemplo configura o preset **sem iniciar provider**. Templates legados
+podem manter seleção `model_orchestration.mode: manual`. O coordenador
+gerenciado usa `execution.runtime: managed` para PRD/SPEC legados, 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.
@@ -143,14 +147,26 @@ 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,
+O candidato local v4 usa `codex_native`; o `managed` permanece para projetos
+legados, 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.
+A escolha do principal, o catálogo gerado do filho e a configuração
+efetivamente observada devem aparecer separados. Na v4, o preflight precisa
+conferir capacidade e perfil Codex antes de reservar/despachar cada filho;
+captura posterior comprova o que ocorreu, não corrige uma chamada já feita.
+Se o host não suporta ou não permite confirmar o modelo/effort exigido,
+bloqueie a tentativa com razão explícita. Não afirme que um prompt mudou o
+modelo e não fabrique telemetria.
+
+No Codex, a configuração de um agente customizado em `.codex/agents/*.toml`
+(`model` e `model_reasoning_effort`) tem precedência sobre os defaults globais
+de `[agents]` e sobre a herança do principal. Por isso, conferir só o YAML do
+ZAIP não prova o modelo de um filho nativo: o preflight deve inspecionar o
+papel efetivamente disponível e sua configuração antes do despacho. Se o papel
+fixar um modelo aposentado ou incompatível com o plano, falhe explicitamente;
+não registre GPT-6 como executado com base apenas na intenção do plano.
+Veja a [documentação oficial de subagentes do Codex](https://learn.chatgpt.com/docs/agent-configuration/subagents).
 
 ## Compatibilidade: model_orchestration sem autonomy
 

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

@@ -17,7 +17,7 @@ O Fast do Codex é consumo de créditos da assinatura e não prova que uma requi
 
 ## 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.
+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 `null` nos registros, API, exportação e cálculo; nunca vira custo observado zero. Na UI v4, cards e células numéricas carregados exibem `0` e cobertura “sem medição”, sem o literal “Indisponível”; loading usa skeleton. 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

package/templates/.agents/zaip-aios/guides/26-qualidade-e-release.md

@@ -2,6 +2,11 @@
 
 O candidato de release precisa passar gates locais, clean-room e distribuição pública sem confundir validação técnica com aprovação de produção.
 
+As decisões de [lifecycle v4](28-lifecycle-completo.md#contrato-aprovado-para-a-v4-a-implementar-e-qualificar)
+estão documentadas antes da alteração estrutural. Documentação aprovada não
+equivale a implementação ou nota de produção; qualifique também a distribuição
+instalada, Codex real, modelo/effort observados, fila e UI.
+
 ## Cobertura
 
 `pnpm test:coverage` mede os módulos de domínio e aplica um ratchet versionado:
@@ -39,8 +44,10 @@ remota manual; não é fallback para assinatura ausente. Uma Release GitHub publ
 não prova publicação npm: acompanhe o job até a confirmação do registry. Os comandos
 abaixo são do mantenedor; não presuma que existam no projeto consumidor.
 
-Dados históricos incompletos do Dashboard conservam `null`/indisponível e sua
-cobertura conhecida. Não se exige reconstruir fatos que nunca foram capturados.
+Dados históricos incompletos conservam `null`/cobertura na fonte, API e
+exportação. Na UI v4, cards/células numéricas carregados mostram `0` com
+“sem medição”, sem exibir “Indisponível”; loading não mostra zero. Não se
+exige reconstruir fatos que nunca foram capturados.
 Isso não dispensa paridade entre records, API e UI para o mesmo conjunto conhecido,
 testes dos dados novos, nem fechamento canônico de Tasks sem sucesso inventado.
 
@@ -77,8 +84,10 @@ contra o manifest do próprio pacote, incluindo a Rule Astra, e verifica que
 os READMEs da raiz do consumidor sobrevivem à instalação e à reinstalação.
 O relatório registra a quantidade de arquivos documentais conferidos.
 
-Novos templates mantêm seleção do principal em `manual`, runtime `managed`
-para PRD/SPEC e preset Equilibrado; avulsas preferem execução direta.
+O candidato v4 mantém seleção do principal em `manual`, runtime
+`codex_native` para PRD/SPEC e Tasks avulsas, e preset Equilibrado.
+O npm publicado anteriormente mantém o contrato da sua versão; o TGZ v4
+e a execução real no Codex exigem qualificação própria.
 A documentação não deve confundir
 perfil de instalação com modelo/effort nem apresentar estimativas de tokens
 como economia financeira medida. O escopo automático e os limites Astra
@@ -225,7 +234,7 @@ anteriores, testes simulados de modelos e evidência local não certificam
 o candidato final nem seu uso em produção.
 
 O [guia 19](19-assurance-e-autonomia.md) registra as fronteiras atuais: controle
-preventivo de cotas/modelos somente no despacho gerenciado; avulsa direta exige
+preventivo de cotas/modelos somente no despacho gerenciado; avulsa direta legada exige
 autorização explícita desde a captura e identidade observada, sem executor
 cerimonial. Revisão aplicável, Evidence e Gui continuam obrigatórios.
 

package/templates/.agents/zaip-aios/guides/27-telemetria-git-native.md

@@ -146,6 +146,12 @@ indisponíveis. Por isso:
 - `null` significa desconhecido e nunca é convertido em `0`;
 - “sem custo observado” não significa “custo zero”.
 
+Essa regra governa fonte, API, agregação e exportação. A UI v4 apresenta
+`0` em cards e células numéricas **após** carregar, mesmo quando a fonte é
+`null`, sempre com cobertura/tooltip “sem medição”; não apresenta o texto
+“Indisponível” nesses componentes. Durante loading, use skeleton. O numeral
+visual não pode alimentar totais, médias, preços ou Evidence como zero real.
+
 ## Operação e recuperação
 
 1. Não edite nem remova manualmente o spool, chunks, manifestos ou writer ID.

package/templates/.agents/zaip-aios/guides/28-lifecycle-completo.md

@@ -1,12 +1,119 @@
 # Lifecycle de Conversations, Tasks, SPECs e PRDs
 
-Este documento é a referência pública do lifecycle implementado pelo ZAIP-AIOS. Status persistido, Run, coluna do Kanban e reconciliação possuem responsabilidades distintas e não devem ser inferidos uns dos outros.
+Este documento separa o lifecycle existente do contrato aprovado para a v4.
+Status persistido, Run, coluna do Kanban e reconciliação possuem
+responsabilidades distintas e não devem ser inferidos uns dos outros.
+
+## Contrato aprovado para a v4 (a implementar e qualificar)
+
+As regras a seguir são decisões de produto, **não** prova de que o runtime,
+hooks, Dashboard ou pacote npm atuais já as impõem. A qualificação deve
+comparar código-fonte, artefato empacotado e uso real no Codex.
+
+1. Pergunta/análise read-only é Conversation, sem Task ou subagente. Pedido de
+   ação independente vira Task avulsa e usa subagentes nativos Codex, mesmo
+   quando o texto não menciona Task. Mencionar PRD/SPEC não os cria; crie macro
+   apenas por pedido explícito e mantenha `draft` até `ready` ou `execute`
+   explícito. Trabalho avulso crítico pode recomendar um macro, sem converter
+   automaticamente nem paralisar a ação já autorizada.
+2. “Crie e execute PRD/SPEC” pode acontecer no mesmo **turno do Codex**. A
+   definição usa sua Run `interaction`; a implementação usa outra Run
+   `delivery`, vinculada ao mesmo alvo e turno. Nunca reutilize ou reescreva a
+   Run de definição como se tivesse executado o produto. “Crie” isolado
+   termina em `draft`; `ready` não executa; `execute` não precisa passar
+   temporariamente pelo card Pronto para Executar.
+3. A Task avulsa é sequencial. Paralelismo produtivo só ocorre para Tasks de
+   PRD/SPEC em DAG planejada, com independência, escopos e recursos
+   compatíveis. Cada tentativa de Task termina `completed`, `blocked`,
+   `failed` ou `cancelled` antes de a Run responsável encerrar. Na falta de
+   prova/decisão, o fallback é `blocked`, com causa e condição de retomada;
+   nunca invente sucesso ou cancelamento. SPEC/PRD aguardam **todas** as
+   Tasks da DAG em estados terminais. Dependentes inviabilizadas por uma
+   Task bloqueada/falhada recebem terminal objetivo; somente depois disso e
+   dos gates parentais o macro pode ser entregue ou terminalizado com causa.
+4. Cada rodada horária, se o usuário tiver instalado a automação Codex,
+   reivindica somente **um** item superior `ready`: PRD, depois SPEC
+   independente, depois Task avulsa. Dentro da classe respeita a prioridade
+   manual do Kanban. Descendentes, ativos e terminais não são candidatos.
+   Lease e releitura do estado impedem seleção duplicada. Arquivos Git não
+   acordam o Codex; não prometa trabalho após o host parar.
+5. O preset `balanced` admite três replanejamentos reais por Task, com
+   diagnóstico Sol/high → Sol/high → Astra/high. Reserva antes do despacho,
+   evento observado, hipótese nova, teste discriminante e ledger imutável
+   evitam recontagem ou alegação de tentativa não executada. O controle
+   gerenciado existente não intercepta qualquer `spawn_agent` nativo; a v4
+   precisa implementar um preflight compatível com o host e bloquear quando
+   modelo, effort ou ferramenta requeridos não puderem ser assegurados.
+6. A reconciliação global do backlog continua manual. A tentativa **atual**
+   pode ser conciliada de modo idempotente ao fechamento ou no próximo evento
+   observável da mesma Task/turno; não há garantia de código rodando após o
+   Codex encerrar. Dashboard e scheduler apenas mostram/retomam fatos
+   canônicos, sem inferir aprovação.
+7. Depois do carregamento, cards e células **numéricas** do Dashboard exibem
+   `0` para ausência de medição; não exibem a palavra “Indisponível”. Mostram
+   também cobertura/tooltip “sem medição”, pois zero observado é diferente.
+   Durante carregamento exibem skeleton, não zero. Records, APIs, exports e
+   cálculos preservam `null`/cobertura parcial; zero visual nunca altera a
+   fonte canônica nem entra em somas como observação.
+
+O candidato local v4 usa `codex_native` no schema e no template npm. O modo
+não inicia um processo autônomo separado; a efetividade da rota nativa ainda
+depende da capacidade real da sessão Codex. Compatibilidade legada permanece
+separada do caminho padrão novo. Isso não comprova publicação no npm.
+
+## Fronteiras nativas e prova de compatibilidade
+
+Esta é a matriz de aceite para o contrato acima. Um texto em `AGENTS.md`, Rule
+ou skill instrui o agente, mas não altera sozinho o seletor de modelo do host,
+não intercepta toda chamada e não cria um relógio. O caminho v4 usa as
+ferramentas reais do Codex e valida capacidades disponíveis na sessão antes
+de prometer uma garantia.
+
+| Fronteira | Comportamento exigido para a v4 | Prova antes de anunciar suporte |
+| --- | --- | --- |
+| Intake | Separar Conversation de ação e correlacionar turno, intenção e alvo sem Task artificial. | Fixtures para pergunta, ação avulsa, criação `draft`, `ready`, execução e “crie e execute”; ausência de artefatos indevidos. |
+| Subagente nativo | Em toda Task avulsa, despachar um filho real e aguardar seu resultado; execução produtiva sequencial. Só uma DAG de PRD/SPEC autoriza filhos produtivos paralelos. | Captura de `spawn_agent`, identidade, modelo/effort solicitados e efetivamente observáveis, resultado terminal e nenhuma Task concorrente fora da DAG. |
+| Modelo e esforço | Consultar agente/perfil que o host disponibiliza. Validar a rota antes do spawn; preservar seleção manual do principal e distinguir intenção de configuração efetiva. | Teste com agente GPT-6 válido, modelo não disponível e fallback inesperado. Sem comprovação da configuração efetiva, manter telemetria `null` e bloquear a garantia automática. |
+| Replan | Reservar e registrar até três diagnósticos reais no Equilibrado, Sol/high, Sol/high, Astra/high; plano exige hipótese nova e teste que distingue a causa. | Ledger idempotente, casos de erro, interrupção, retry e capacidade ausente; não contar prompt, timeout ou reserva sem execução como diagnóstico concluído. |
+| Fechamento | Aguardar filhos e provas, executar Gui como último filho e aplicar sua decisão. Se Gui não iniciar, falhar ou a Run parar, o caminho confiável de fechamento registra `blocked` com motivo e retomada, sem inventar decisão de Gui. | Testes de Stop, interrupção e replay; nenhuma tentativa **formalmente encerrada** fica `executing`/`verifying`; recibo recuperável quando a escrita falha. |
+| Agenda | Instalar somente a pedido uma tarefa agendada nativa do desktop para um item superior `ready` por rodada, com lease e prioridade do Kanban. | Inspeção da automação realmente criada, duas rodadas sem duplicação e teste de worktree/local; sem app/máquina ativa, informar ausência de execução. |
+| Dados e UI | Reconciliar fontes canônicas e worktrees; mostrar skeleton durante carga e `0` visual nos campos numéricos sem medição, com cobertura explícita. | Comparar records → SQLite → API → cards/tabelas; `null` continua em API/export/cálculo, inclusive nos períodos Hoje/Ontem/Esta Semana. |
+| Distribuição | Builder e projeto novo/atualizado pelo npm instalam os mesmos adapters, Rules, skills e configuração suportada. | Testar TGZ exato em fixture limpa e atualização Windows/PowerShell, `doctor`, adaptadores, ciclo Codex e idempotência. |
+
+Os [subagentes do Codex](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+permitem perfis próprios e herança de modelo/effort; a disponibilidade
+concreta e o agente escolhido dependem da sessão. Os
+[hooks do Codex](https://learn.chatgpt.com/docs/hooks) cobrem muitas
+ferramentas locais, mas admitem caminhos especializados fora dessa cobertura.
+`PreToolUse` pode impedir chamadas cobertas; `Stop` pode solicitar uma nova
+continuação, não provar que o trabalho terminou, nem impedir uma interrupção
+humana. Por isso o hook é checkpoint e reparo observável, nunca substituto
+universal de estado canônico, Gui ou ferramenta de despacho. As
+[tarefas agendadas](https://learn.chatgpt.com/docs/automations) têm execução
+própria do app; em projeto local dependem de computador ligado e app ativo.
+O agendamento não é instalado só porque os arquivos existem no Git.
+
+Se o processo for encerrado antes do Stop ou da escrita, nenhum componente
+local consegue garantir a transição **naquele instante**. A garantia honesta é
+um evento durável recuperável e a conciliação na próxima execução observável;
+até lá, o estado pode continuar aberto e o Dashboard deve indicá-lo, não
+inventar um terminal. Esse limite do host não autoriza encerrar a Run com
+`executing` como se fosse sucesso.
+
+Lacunas verificadas neste candidato: a CLI recusa `task block` direto sem decisão
+de Gui, mas `run finish` aplica `blocked` como fallback quando é realmente
+chamado sem essa decisão. Uma interrupção antes desse comando ainda pode deixar
+a Task em `executing` até a retomada/reconciliação. A fila agendada agora
+reivindica no máximo um item por lease; a rota Sol/Sol/Astra não está provada
+para toda chamada nativa. São itens de implementação, não decisões humanas
+pendentes. A documentação é aprovada quando descreve essas lacunas; o produto
+só está pronto quando a matriz passa no Codex e no pacote instalado.
 
 ## Classificação de entrada
 
 Aliases são resolvidos com alvo e status persistido, nunca por palavra isolada. `pronto`, `deixe/coloque em Pronto para Executar` e `ready-to-execute` resolvem para `ready`. `finalizar|concluir|finalize|conclude` em PRD/SPEC `draft|ready` lapidam e resolvem para `ready`; em trabalho ativo, “conclua a execução/finalize a implementação” continua Tasks e gates. Somente `entregar|deliver` após gates solicita entrega terminal.
 
-`implemente` sem alvo abre somente uma Conversation de planejamento; em `draft` finaliza o plano sem executar, em `ready` executa e em `active|blocked|failed` continua, retoma ou cria rework. `desenvolva|melhore|aprimore` sempre planeja/refina/rework. PRD cancelado é imutável e recebe sucessor `draft` com tag `rework` e `rework_of_prd_id`.
+No contrato atual, `implemente` sem alvo abre Conversation de planejamento; na v4, quando houver objetivo independente de ação, entra como Task avulsa. Em PRD/SPEC `draft`, só executa com intenção explícita de executar o macro; criar/refinar isoladamente mantém `draft`. Em `ready`, executar inicia; em `active|blocked|failed`, continua/retoma/rework conforme estado. `desenvolva|melhore|aprimore` com intenção explícita de ação independente também não é reduzido a planejamento só pelo verbo. PRD cancelado é imutável e recebe sucessor `draft` com tag `rework` e `rework_of_prd_id`.
 
 ## Criação completa de PRD e SPEC
 
@@ -66,7 +173,7 @@ Quando o host expõe Calls, a Run/Sub-Run agrega quantidade conhecida, terminais
 
 Cada tentativa de Task tem um orquestrador responsável. Uma raiz física Task-scoped é esse responsável; uma raiz macro delega um por Task, preservando ancestry real. Um executor é escolhido pelas capacidades e pela elegibilidade declarada no catálogo: `zaip-agent-builder` e `zaip-agent-task-executor` podem executar delivery, e `zaip-agent-analyst` pode executar interaction. Revisão, auditoria e integração podem participar. Depois que todos os demais descendentes terminarem, o orquestrador deve chamar `zaip-agent-finalizer` como último Sub-Run, com propósito `finalization`, como filho direto do responsável da Task, não do executor.
 
-O finalizador é read-only: avalia resultados, gates e Evidence e retorna somente o status terminal proposto, motivo e referências. A CLI aplica deterministicamente a transição. O início do finalizador cria uma barreira: ele não pode começar com descendentes ativos e nenhum filho novo pode iniciar depois dele. Finalizador ausente, incompleto ou falho resulta em `blocked`, nunca em Task presa em `executing` ou `verifying`.
+O finalizador é read-only: avalia resultados, gates e Evidence e retorna somente o status terminal proposto, motivo e referências. A CLI aplica deterministicamente a transição após a decisão real. O início do finalizador cria uma barreira: ele não pode começar com descendentes ativos e nenhum filho novo pode iniciar depois dele. **Contrato-alvo v4:** finalizador ausente, incompleto ou falho produz `blocked` por um caminho confiável separado, nunca uma aprovação sintética. No candidato atual, a CLI ainda pode deixar a Task em `executing` porque rejeita bloqueio direto sem Gui; essa lacuna precisa de correção e teste.
 
 No modo nativo do Codex, a orquestração materializa essa etapa como um envelope de delegação com `purpose: finalization`, `agent_id: agent-finalizer`, escopo de escrita vazio e chave de idempotência própria. Uma Execution em `verifying` só recebe esse envelope; o host deve iniciar a Sub-Run real correspondente e registrar a telemetria dela. O framework não cria Run, Call, custo ou resultado sintético quando o host não a executa.
 
@@ -77,7 +184,9 @@ uma declaração versionada cujo vínculo só pode complementar Evidence quando
 `confirmed` e coerente; os demais estados preservam pendência ou falha. Veja o
 [contrato de prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
 
-Exemplo:
+Depois de capturar a decisão real do finalizador, o orquestrador pode aplicar
+o fechamento pela CLI. O trecho abaixo **não** funciona como atalho para
+`task block` ou `run finish` sem essa decisão já persistida:
 
 ```bash
 zaip run finish RUN-ID \
@@ -96,9 +205,13 @@ Antes de uma Run raiz terminar, sua Task deve estar em um destes estados:
 - `failed`: erro técnico/integridade que impediu a execução válida;
 - `cancelled`: pedido humano explícito.
 
-`executing` e `verifying` nunca são estados válidos no fim da tentativa. Use `task resume` para `blocked` e `task rework` para `failed`; ambas preservam a Task, e cada nova entrada em execução incrementa a tentativa. `completed` e `cancelled` não reabrem.
+`executing` e `verifying` nunca são estados válidos no fim **formalmente persistido** da tentativa. Use `task resume` para `blocked` e `task rework` para `failed`; ambas preservam a Task, e cada nova entrada em execução incrementa a tentativa. `completed` e `cancelled` não reabrem.
 
-Interromper a geração é uma interrupção retomável e resulta em `blocked`. “Cancelar a Task” é uma decisão explícita e resulta em `cancelled`.
+Interromper a geração exige recuperação retomável; quando o evento de
+interrupção for observado e a escrita funcionar, o alvo é `blocked`. Morte
+abrupta do processo pode deixar o estado pendente até o próximo evento
+observável, como descrito acima. “Cancelar a Task” é decisão explícita e
+resulta em `cancelled` somente quando persistida.
 
 ## Agregação de SPEC e PRD
 
@@ -106,12 +219,15 @@ Quando a primeira Task filha inicia, SPEC e PRD relacionados passam para `active
 
 - Task bloqueada/falhada mantém o macro em Execução para que outras Tasks e decisões parentais continuem.
 - SPEC/PRD aguardam todas as Tasks e Runs filhas.
-- Depois que todas as Tasks concluem, o macro entra em Verificação.
-- Delivery exige gates, integração, Acceptance Criteria, outcomes e Evidence próprios do pai.
+- Depois que todas as Tasks da DAG ficam terminais, o macro pode entrar em
+  Verificação quando todas concluíram; bloqueios/falhas e dependentes inviáveis
+  são fechados com causa antes de decidir o resultado parental.
+- Delivery exige gates, integração, Acceptance Criteria, outcomes e Evidence
+  próprios do pai. Um pai não é `delivered` se uma filha bloqueou/falhou.
 
 ## Reconciliação manual
 
-O dashboard executa `zaip run reconcile --open --json` somente depois que o usuário confirma o popup Reconciliar. Não há reconciliação global ao abrir o dashboard, em cada turno ou em intervalo automático.
+O dashboard executa `zaip run reconcile --open --json` somente depois que o usuário confirma o popup Reconciliar. Não há reconciliação **global** ao abrir o dashboard, em cada turno ou em intervalo automático. O contrato-alvo v4 acrescenta conciliação **direcionada à tentativa atual** no fechamento/Stop observado ou no próximo evento Codex da mesma Task, nunca uma varredura global silenciosa.
 
 O algoritmo é idempotente e conservador:
 
@@ -162,5 +278,7 @@ de reservas do runtime. Ausência de Evidence é bloqueio, erro técnico
 comprovado é falha e tempo não determina abandono.
 
 Fechamento técnico, estado canônico da Task, projeções e entrega parental
-precisam ser confirmados separadamente. A preferência avulsa direta não remove
-o gate de executor capturado ainda exigido pelo contrato atual.
+precisam ser confirmados separadamente. A exceção de raiz avulsa direta
+autorizada pertence à compatibilidade do contrato atual; no padrão Codex-native
+da v4, a Task avulsa terá executor subagente nativo observado. Nenhum dos dois
+caminhos dispensa Evidence, gates e decisão real de Gui.