@zaip-ai/cli 1.3.0 → 1.3.2

package/templates/.agents/zaip-aios/guides/20-instalacao-detalhada.md

@@ -4,24 +4,45 @@ Este guia descreve o modelo de lifecycle V2 no layout V3. Durante a transição,
 
 ## Pré-requisitos
 
-- Node.js 22 ou superior;
-- pnpm 11;
+- Node.js compatível com o pacote (declara 22+); para Dashboard, confirme `node:sqlite` disponível, como no ambiente de referência 22.16.0;
 - Git;
 - permissões de escrita no repositório consumidor.
 
+O consumidor não precisa compilar o monorepo nem instalar pnpm para executar
+o runtime distribuído. No checkout mantenedor, use o pnpm fixado em
+`packageManager` (11.12.0 neste snapshot), com `corepack pnpm` quando disponível.
+
+## Instalação pública no projeto consumidor
+
+Na raiz do projeto-alvo:
+
+```bash
+npx @zaip-ai/cli@latest init --dry-run
+npx @zaip-ai/cli@latest init
+node .agents/runtime/bin/zaip.mjs doctor --json
+```
+
+Revise o dry-run antes da instalação. `@latest` seleciona a versão publicada,
+não alterações ainda locais neste repositório. O binário público `zaip` é o
+instalador; nos exemplos de lifecycle deste guia, `zaip ...` é uma abreviação
+de `node .agents/runtime/bin/zaip.mjs ...` no projeto consumidor. Use o caminho
+explícito para evitar colisão entre os dois CLIs.
+
 ## Construir o CLI
 
-No repositório-fonte:
+Somente no repositório-fonte, para manutenção do framework:
 
 ```bash
-pnpm install
-pnpm build
+corepack pnpm install --frozen-lockfile
+corepack pnpm build
 node packages/cli/dist/index.js version
 ```
 
-Nos exemplos abaixo, substitua `zaip` por `node /caminho/zaip-aios/packages/cli/dist/index.js` se o binário ainda não estiver no `PATH`.
+Nesse checkout compilado, use `node packages/cli/dist/index.js ...` para os
+comandos de lifecycle. Em `--workspace`, informe o destino autorizado; não
+confunda a raiz fonte com o projeto consumidor.
 
-## Instalar ou atualizar
+## Setup pelo CLI de lifecycle
 
 Faça primeiro um dry-run e revise conflitos:
 
@@ -76,7 +97,16 @@ zaip migrate rollback --workspace /caminho/do/projeto --migration ID
 
 Use Task-first para uma alteração pontual e bem delimitada. Use SPEC quando o objetivo técnico exige várias Tasks, dependências ou execução autônoma longa. Use PRD quando é necessário traduzir objetivo de negócio, usuários, métricas e restrições em uma ou mais SPECs.
 
-PRD e SPEC são opcionais. Toda mensagem é capturada por uma Execution e uma Run. Para pergunta, feedback ou análise pontual somente leitura, use `zaip conversation start` e `zaip conversation finish`: é criada uma Execution `interaction`, sem Task ou Change artificial. A criação ou o refinamento explícito de PRD/SPEC `draft` é a exceção de definição e pode persistir o macro e seu PreparedPlan na própria `interaction`, sem Task, Change ou Execution `delivery`. Fora dessa exceção, qualquer alteração intencional e persistente em código, documentação, configuração ou outro arquivo do repositório ou do computador exige uma Execution `delivery`, Task materializada e Run raiz de orquestração ativa antes da primeira escrita.
+PRD e SPEC são opcionais. O intake captura uma vez por turno observável;
+continuação reutiliza o foco válido e publicação puramente Git não cria
+lifecycle. Para pergunta, feedback ou análise read-only, `conversation start`
+e `conversation finish` registram uma interaction sem Task/Change artificial.
+Criar/refinar explicitamente PRD/SPEC `draft` pode persistir macro e PreparedPlan
+na própria interaction, sem delivery. Fora dessa exceção, alterações persistentes
+de código, documentação ou configuração exigem delivery, Task materializada e
+Run raiz ativa antes da escrita; caches/builds e projeções geradas seguem as
+isenções da Rule de workflow. Interaction read-only sem descendentes não exige
+executor nem finalizador.
 
 Uma solicitação direta de ação entra em Execução; ela não passa artificialmente por Definição ou Planejamento. Uma Task independente que foi apenas preparada e ainda não começou fica em Pronto para executar. No quadro, Definição é exclusiva de PRDs em draft e Planejamento é exclusivo de SPECs em draft. O contrato completo está em [Lifecycle de trabalho](28-lifecycle-completo.md).
 
@@ -200,6 +230,12 @@ verificação não se aplica, registre `status: not_applicable` e a justificativ
 permanece pendência. O dashboard contabiliza testes e considera uma etapa rastreada somente quando
 existe timestamp de origem, sem substituir ausência pelo horário da consulta.
 
+Quando houver prova observável por AC, siga o contrato
+[canônico](../../skills/zaip-skill-change/references/observable-evidence.md).
+`validation observe` registra uma declaração sanitizada inline; não abre arquivo
+de entrada, não executa o procedimento e não cria Validation aprovada. Somente
+uma observação `confirmed` e vinculada pode complementar Evidence já compatível.
+
 Decisões curtas ficam inline. Se uma decisão exigir ADR, salve-o em `decisions/` dentro da própria Change ou Execution e mantenha o resumo no Markdown principal.
 
 ## Runs e custos

package/templates/.agents/zaip-aios/guides/21-telemetria-monitor-custos.md

@@ -1,30 +1,24 @@
 # Contrato de telemetria do Monitor de Custos
 
-Atualizado em 26 de julho de 2026.
+Este guia descreve o contrato e não declara cobertura, totais ou preços de um período como estado atual.
 
 ## Escopo
 
-O Monitor de Custos é uma visão financeira de invocações LLM. Cada linha exibida deve possuir:
-
-- tokens coletados;
-- custo BRL calculável a partir dos tokens e do catálogo histórico;
-- duração de origem observada.
-
-Runs de lifecycle não são automaticamente linhas financeiras. Uma Run sem chamada LLM, ou com chamada sem correspondência local verificável, permanece no histórico de Operação e não entra no Monitor. Isso impede que `0` seja usado para esconder falta de coleta.
+O Monitor de Custos é uma visão financeira da população de Runs de Operação. Cada linha preserva a disponibilidade de suas métricas: tokens sem captura, custo sem componentes/tarifa/câmbio suficientes e duração sem fonte permanecem indisponíveis; não são convertidos em `0` nem removidos para produzir uma cobertura artificial. A elegibilidade de uma estimativa de custo exige tokens e identidade de preço verificáveis, mas uma Run de lifecycle não precisa ter chamada LLM para continuar visível com lacunas explícitas.
 
 ## Fonte e proveniência
 
 A projeção é **manifest-first**: usa os manifests e registros Git como fonte canônica e a telemetria local apenas para uma reconciliação com correspondência exata. O Dashboard não usa SQLite como fonte de dados do Monitor de Custos.
 
-Tokens, custo e duração exibidos no Monitor mantêm proveniência observada. Uma duração limitada de lifecycle com proveniência `legacy_inferred` pode permanecer em Operação e Rastreabilidade, mas não completa uma linha financeira nem entra em seus agregados.
+Tokens, custo e duração devem exibir sua proveniência. Tokens e configuração efetiva de modelo/effort só são observados quando a fonte os informa; defaults planejados não preenchem esses campos. A projeção pode exibir duração `observed`, `reconciled`, `legacy_inferred` ou `estimated`. Apenas `observed` é medição da fonte; as demais são derivadas e não satisfazem um critério que exija duração capturada.
 
 ## Cobertura e valores exibidos
 
-`Cobertura de 100%` neste monitor significa que todas as linhas financeiras exibidas têm tokens, custo e duração observada. A contagem e a cobertura precisam ser recalculadas após qualquer mudança no critério de elegibilidade; não reutilize uma auditoria anterior como prova do conjunto novo.
+Cobertura é calculada por métrica e pelo conjunto filtrado. `100%` para tokens, custo ou duração só significa que aquela métrica está completa segundo sua definição e proveniência declarada; não demonstra automaticamente que as outras estão completas ou que a duração foi observada. Recalcule a cobertura após qualquer mudança de critério e não reutilize uma auditoria anterior como prova do conjunto novo.
 
-Os agregados de Conversas, Providers, Agentes, Modelos, Diário, Mensal e Anual usam as mesmas invocações financeiras da tabela. Um agente configurado sem invocações no período é um agregado vazio real e exibe zero. Duração ausente exibe `Indisponível`; o valor bruto e sua proveniência continuam disponíveis para auditoria.
+Os agregados de Conversas, Providers, Agentes, Modelos, Diário, Mensal e Anual usam o mesmo conjunto filtrado da tabela e preservam as lacunas de cada métrica. Um agente configurado sem invocações no período é um agregado vazio real e exibe zero. Duração ausente exibe `Indisponível`; uma duração derivada deve mostrar sua proveniência e não ser lida como captura.
 
-Não se deve converter em zero um registro que esteja fora do conjunto financeiro por ausência de coleta. Na auditoria, 126 Runs de Operação estavam nessa condição: 111 sem chamada LLM e 15 sem correspondência local única. Elas não alteram a cobertura das linhas financeiras.
+Não use contagens, totais ou percentuais de auditorias passadas como diagnóstico atual. Consulte o período e os filtros da execução auditada; uma lacuna de coleta continua sendo lacuna, mesmo quando há estimativa ou reconciliação exibida.
 
 ## Filtros e totais
 
@@ -47,6 +41,6 @@ Filtros preenchidos somente com data são inclusivos: a data inicial começa em
    node scripts/validate-release-parity.mjs --release
    ```
 
-3. Consulte `/api/v2/cost-monitor` no período auditado e confirme, para cada grupo, que `missing_tokens`, `missing_cost_brl` e `missing_duration` são zero. Em seguida, compare o total de custo retornado com o card da Visão geral usando exatamente os mesmos filtros.
+3. Consulte `/api/v2/cost-monitor` no período auditado. Confirme que os campos de cobertura e proveniência são coerentes com o objetivo da auditoria; para alegar telemetria capturada, exija tokens, custo e duração observados, não apenas totais ou estimativas. Em seguida, compare o total de custo retornado com o card da Visão geral usando exatamente os mesmos filtros.
 
-Se houver uma lacuna, preserve-a como ausência até existir uma correspondência exata e única. Ação de reconciliação não autoriza estimar token, custo ou duração.
+Se houver uma lacuna, preserve-a como ausência até existir uma correspondência exata e única. Reconciliação ou estimativa podem ser exibidas com proveniência, mas não autorizam alegar token, custo ou duração capturados.

package/templates/.agents/zaip-aios/guides/22-fluxos-e-roteamento.md

@@ -20,6 +20,11 @@ Tentativa → gates e review
   correção necessária → classificar rework → recalibrar agente, modelo e esforço → nova tentativa
 ```
 
+Observação por AC é um checkpoint de prova, não um supervisor de tempo ou um
+atalho de aprovação: o registro não executa o procedimento, não transforma
+resultado pendente em verde e não dispensa review/finalizador. Consulte o
+[contrato canônico](../../skills/zaip-skill-change/references/observable-evidence.md).
+
 Em PRD/SPEC com `model_orchestration.mode:auto`, trabalho simples e delimitado pode usar Luna/low, execução padrão Terra/medium e ambiguidade, transversalidade ou rework estrutural Sol/high ou xhigh. Conversation e Task-first preservam a seleção manual do host/Codex. Criticidade amplia assurance; não eleva modelo mecanicamente.
 
 ## Entradas e planejamento

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

@@ -31,7 +31,7 @@ Quando `model_orchestration.mode` estiver como `manual`, o ZAIP:
 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. Quando algum valor não estiver disponível, usa `default_model`, `default_effort` e `default_velocity` de `project.yaml`. Nesta versão, os três fallbacks são literalmente `manual`; o aviso nunca usa `não informado` nem infere valores pelo comportamento aparente do modelo.
+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:
 
@@ -159,7 +159,7 @@ O catálogo mantém IDs internos estáveis como `agent-builder`, enquanto o adap
 | --- | --- | --- |
 | `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` | Sol `medium` | Sol `high` para revisão complexa delimitada |
+| `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 |
@@ -404,7 +404,7 @@ policy.runtime_defaults explícito da Execution
 
 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.
 
-O cabeçalho de cada Run ou Sub-Run preserva a configuração resolvida, e `model.selection.recorded` registra a mesma 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. Run raiz é a chamada do orquestrador e possui `parent_run_id: null`; Sub-Run possui pai:
+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:
@@ -429,7 +429,7 @@ agent_run:
     - terra-implementation-baseline
 ```
 
-Requested e effective não devem ser confundidos, pois o runtime ou serviço pode aplicar fallback ou reroteamento.
+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.
 
@@ -443,7 +443,7 @@ O dashboard cria visões separadas para Runs e Sub-Runs, mas não cria entidade
 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 e não muda o cabeçalho. Valores indisponíveis permanecem `null`; prompt e reasoning privado nunca são armazenados.
+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
 
@@ -451,7 +451,7 @@ Todas as Calls da mesma Run reutilizam a configuração planejada. Se o provider
 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`; não infere o baseline automático para Task avulsa.
+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.

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

@@ -1,6 +1,6 @@
 # Auditoria do cálculo de custo equivalente via API
 
-Atualizado em 15 de julho de 2026.
+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
 
@@ -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 é uma superfície financeira: uma invocação só aparece quando possui tokens, custo e duração de origem observados. Lifecycle e telemetria parcial continuam disponíveis em Operação e Rastreabilidade. `null` permanece `Indisponível`; nunca é convertido em zero. Duração inferida de registros legados pode ser exibida apenas nessas superfícies não financeiras, identificada como inferida.
+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
@@ -42,9 +42,9 @@ 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 prático — GPT-5.6 Sol, Standard
+## Exemplo didático — GPT-5.6 Sol, Standard
 
-Tarifas atuais do catálogo: input US$5, cache US$0,50 e output US$30 por 1M. Para 1.000.000 input, 800.000 cache, 100.000 output e 70.000 reasoning:
+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
@@ -55,7 +55,7 @@ reasoning = US$ 0,00 adicional (já está nos 100.000 output)
 total = US$ 4,40
 ```
 
-Com USD/BRL 5,45: `4,40 × 5,45 = R$ 23,98`.
+Com uma cotação **hipotética** USD/BRL de 5,45: `4,40 × 5,45 = R$ 23,98`.
 
 ## Service tier, contexto e dados incompletos
 
@@ -63,11 +63,11 @@ Com USD/BRL 5,45: `4,40 × 5,45 = R$ 23,98`.
 - 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 são estimativas equivalentes, nunca valores de fatura.
+- 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: modelo efetivo, velocidade observada, **Cenário velocidade API**, input, cache, output, reasoning, tarifas selecionadas, USD e BRL. `Priority (derivado de Fast)` significa cenário de estimativa, não cobrança API comprovada. `USD/BRL registrado` e `BRL registrado` são a fotografia histórica quando existirem; `Estimativa API (BRL)` usa a cotação global atual.
+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
 
@@ -75,7 +75,7 @@ A aba **Modelos** não lista Runs. Cada linha agrega todas as Runs do modelo den
 
 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 catálogo atual o último normalmente é zero, porque reasoning já está incluído em output. O câmbio efetivo é `BRL estimado / USD estimado`, calculado somente depois da soma em USD.
+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
 

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

@@ -1,6 +1,6 @@
 # Fontes oficiais de preços OpenAI
 
-Consulta em 15 de julho de 2026. Valores operacionais ficam no catálogo versionado `.agents/config/pricing/models.json`; esta página é o registro de auditoria das fontes.
+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 |
 | --- | --- | --- |
@@ -11,8 +11,9 @@ Consulta em 15 de julho de 2026. Valores operacionais ficam no catálogo version
 
 ## Regras de atualização
 
-1. Atualize primeiro a fonte oficial e a data de consulta.
+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.

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

@@ -8,29 +8,111 @@ O candidato de release precisa passar gates locais, clean-room e distribuição
 
 - 80% de lines;
 - 80% de functions;
-- 70% de branches;
+- 75% de branches;
 - 80% de statements.
 
 O composition root executável `packages/cli/src/index.ts` é coberto pelos testes CLI/release E2E. O payload gerado `packages/cli/src/dashboard-template.ts` é coberto pela paridade do template. Ambos ficam fora da cobertura unitária para não misturar integração e geração de distribuição com unidade de domínio.
 
 O ratchet usa o maior valor entre o floor atual e o baseline versionado. Uma medição menor falha; o baseline não pode ser atualizado para encobrir regressão.
 
-## Ordem de qualificação
+## Gates agregados e diagnósticos
 
-1. `pnpm validate:github:prepared`
-2. `pnpm test:coverage`
-3. `pnpm test:release-e2e`
-4. `pnpm turbo run test:e2e --filter=@zaip-ai/dashboard-e2e`
-5. `pnpm audit --prod --audit-level high`
-6. `pnpm --dir public-cli verify`
-7. `pnpm release:verify` no worktree final limpo
+O gate de PR é o job único `github-equivalent` de
+`.github/workflows/quality.yml`, em `ubuntu-latest`: instala dependências,
+instala Chromium e executa `validate:github:prepared`, auditoria de produção,
+cobertura, release E2E e dashboard E2E. Esses subchecks são etapas desse gate
+agregado; não são uma receita adicional que, isoladamente, aprove uma release.
 
-`release:artifacts` deve estabilizar os manifests antes de `sync:framework-lock`. Depois do lock, o template público é sincronizado e auditado novamente.
+O workflow `.github/workflows/publish-cli.yml` é separado: seu job `verify`
+usa matriz real Node 22 e 24 para `pnpm verify`; a auditoria e o artefato de
+release ocorrem somente na linha Node 24, ambas em Ubuntu. Publicação e smoke
+só seguem após a matriz aprovada. Esse `verify` roda dentro de `public-cli`,
+não é o script homônimo da raiz. Os comandos abaixo são do checkout mantenedor;
+não presuma que existam no `package.json` do projeto consumidor.
+
+A publicação compara `dist.integrity` do registro com o SHA-512 do tarball
+verificado. Uma versão já existente só é aceita quando o conteúdo é idêntico.
+Somente `E404` estruturado indica ausência; autenticação, rede, resposta
+inválida ou integridade diferente impedem publicar. Após uma publicação
+autorizada, a confirmação do mesmo tarball usa retry finito de propagação.
+Esse controle não publica automaticamente quando a qualificação local passa.
+
+| Objetivo | Comando da raiz e alcance |
+| --- | --- |
+| Preparar artefatos | `corepack pnpm release:artifacts` compila e gera runtime/template. Não publica nem qualifica por si só. |
+| Atualizar integridade após mudança gerenciada intencional | `corepack pnpm sync:framework-lock`, depois `corepack pnpm validate:framework-lock`; não usar para aceitar drift desconhecido. |
+| Diagnosticar um check | Executar apenas o teste/check pertinente e registrar seu resultado. Isso não substitui a qualificação completa. |
+| Qualificar localmente | `corepack pnpm release:verify` agrega instalação pública, validação preparada, cobertura, release E2E, dashboard E2E, audit e árvore limpa. |
+| Verificação completa da raiz | `corepack pnpm verify` acrescenta orçamento de Rules e contrato antes de `release:verify`. Não precisa repetir manualmente cada subcomando no mesmo candidato. |
+
+Finalize as escritas gerenciadas antes de sincronizar o lock; após alterá-lo,
+sincronize/audite novamente o template público. Execute gates geradores em
+checkout/worktree isolado para preservar trabalho concorrente. Gates locais,
+artefato exato, CI terminal e produção continuam sendo provas distintas.
+
+### Falhas de desempenho no dashboard
+
+Reproduza a rota, período, filtro, offset e tamanho da página que falharam.
+Separe a primeira consulta sem resultado em cache da navegação já aquecida;
+uma página rápida em cache não comprova o custo de exportar páginas distintas.
+Correlacione o clique com a requisição, a espera pelo servidor, o retorno e o
+fechamento do arquivo. Registre a concorrência do teste e do ambiente.
+
+Timeout não autoriza aumentar limites nem remover a matriz de performance.
+Primeiro diferencie requisição ausente, cancelada, bloqueada e consulta lenta.
+Uma correção de consulta deve preservar filtros, ordenação, total, IDs únicos,
+offsets contíguos e exportação até `has_more=false`. Reexecute o cenário que
+falhou e o gate correspondente no candidato corrigido. Se o pacote anterior
+já estiver publicado, distribua a correção em nova versão imutável.
+
+## Histórico e nova qualificação em 30/08/2026
+
+Snapshot bloqueado em 2026-08-30 para o candidato
+`d00851adfd78b4e4af8e888e270d55ace749607e`: não há release verde declarada.
+A tentativa de reparo isolado do runtime passou 9 de 10 testes e
+falhou em `reports a missing runtime and restores it transactionally`:
+`FLAT_FRAMEWORK_RULES` não classifica
+`.agents/rules/dashboard-ui-consistency.md`, embora a regra esteja no template,
+e a restauração transacional retorna `repaired.applied=false`. A correção do
+instalador está fora daquele recorte e não foi aprovada nem validada.
+
+Também não está verde o teste completo de orçamento das Rules: a folga exigida
+para `run-lifecycle-closure.md` é 867 e o orçamento atual é 840. Isso é uma
+falha registrada, não um snapshot a ser tratado como aprovação. Sem corrigir e
+reexecutar esses gates no candidato apropriado, não declare clean-room,
+qualificação integral, produção ou release aprovados.
+
+O relatório-fonte deste snapshot é
+`.agents/records/changes/2026/08/CHG-2026-08-30-18-18-EVIDENCIAS-OBSERVAVEIS-SEGURAS-K5WJ/artifacts/checks/verification-report.md`
+no repositório mantenedor; ele não é distribuído como histórico do consumidor.
+O status central de readiness não é ligado aqui porque
+`docs/PRODUCTION-COMMERCIAL-READINESS.md` não faz parte do template público
+instalado; um link relativo seria enganoso para consumidores do pacote.
+
+A entrega corretiva posterior `TASK-2026-08-30-19-51-LIBERAR-PRODUCAO-SEGURA-2NA6`
+inclui a Rule ausente no instalador e reduz o texto de encerramento sem
+aumentar o orçamento 840. Os cenários focais de reparo e orçamento foram
+reexecutados com sucesso. O snapshot acima é histórico: não deve ser apagado
+nem usado como resultado do novo candidato. A aprovação da candidata nova
+depende de seus próprios gates completos, artefato, SHA e revisão independente.
+Os resultados finais ficam na Change correspondente no checkout mantenedor,
+não no histórico distribuído ao consumidor.
 
 ## Arquivos efêmeros
 
 `test-results`, `playwright-report`, `coverage`, `.turbo` e `node_modules` nunca pertencem ao pacote portável nem ao manifesto gerenciado. A embalagem e o clean-room aplicam a mesma política de exclusão.
 
+Antes de substituir `public-cli/artifacts` ou executar `npm pack`, o guard de
+release compara o inventário público efetivo do Dashboard com os arquivos
+rastreados pelo Git. Somente os dois outputs declarados do build SQLite,
+`packages/local-runtime/dist/server.cjs` e
+`packages/local-runtime/dist/sqlite-read-model.cjs`, podem ser gerados sem
+rastreamento. Outros arquivos não rastreados, inclusive diagnósticos ignorados
+pelo Git, impedem a embalagem. Uma consulta Git indisponível também bloqueia.
+O guard não remove, move, ignora ou adiciona arquivos ao Git; a limpeza deve
+ser resolvida pelo responsável autorizado, preservando os artefatos anteriores.
+Use o checkout limpo do candidato exato e não publique TGZs de diagnóstico.
+
 ## Evidência e aprovação
 
 Testes passando comprovam validação técnica. Maturidade formal máxima exige ainda:

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

@@ -12,7 +12,9 @@ O caminho implementado possui quatro camadas:
 4. leitura manifest-first no Monitor de Custos, complementada pelos dados de lifecycle já lidos dos manifests canônicos.
 
 O rollout amplo continua condicionado à cobertura observada. Ter o pipeline instalado não autoriza
-rotular métricas ausentes como completas nem transformar valores desconhecidos em zero.
+rotular métricas ausentes como completas nem transformar valores desconhecidos em zero. Duração,
+tokens e custo não capturados permanecem explicitamente indisponíveis; uma reconciliação ou
+estimativa só pode aparecer com proveniência e não passa a ser observação da fonte.
 
 ## Fluxo dos dados
 
@@ -83,7 +85,9 @@ Um resumo preserva:
 
 O custo histórico é agregado apenas quando preço, câmbio e componentes necessários são
 compatíveis. O leitor não reprecifica silenciosamente uma execução antiga. Se qualquer componente
-necessário estiver ausente, o total correspondente permanece `null`.
+necessário estiver ausente, o total correspondente permanece `null`. Modelo e reasoning effort
+efetivos também permanecem indisponíveis quando o host não os informou; não são derivados do
+catálogo, da seleção planejada ou do comportamento aparente.
 
 ### Chunks e manifestos
 
@@ -120,7 +124,8 @@ chunks incompatíveis antes da leitura. O leitor valida:
 Quando há summaries válidos para o período, tokens e custos vindos do manifesto são autoritativos.
 Os dados de lifecycle carregados de `records/lifecycle` continuam fornecendo campos que o resumo não
 conhece. Em particular, uma duração de lifecycle delimitada é preservada quando o summary não possui
-duração observável. Se não houver summaries aplicáveis, o Dashboard preserva os dados de lifecycle e
+duração observável. Essa preservação mantém a proveniência: duração reconciliada, inferida ou
+estimada não deve ser lida como duração capturada. Se não houver summaries aplicáveis, o Dashboard preserva os dados de lifecycle e
 a cobertura disponível; não lê nem recria uma projeção ou arquivo local, e nunca promove a cobertura
 para `complete`.
 

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

@@ -72,6 +72,11 @@ No modo nativo do Codex, a orquestração materializa essa etapa como um envelop
 
 O status técnico da Run/Sub-Run (`completed`, `failed`, `cancelled`) é diferente do resultado da Task (`completed`, `blocked`, `failed`, `cancelled`). Uma Run tecnicamente concluída pode bloquear a Task porque um gate ou Evidence não passou.
 
+Uma observação por AC não altera esse lifecycle nem substitui os gates. Ela é
+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:
 
 ```bash