@zaip-ai/cli 1.0.8 → 1.3.1

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

@@ -0,0 +1,366 @@
+# Como instalar e rodar o ZAIP-AIOS
+
+Este guia descreve o modelo de lifecycle V2 no layout V3. Durante a transição, layouts V1/V2 continuam disponíveis somente para leitura e migração; novos artefatos e seus manifests Git-native usam `.agents/records`.
+
+## Pré-requisitos
+
+- 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
+
+Somente no repositório-fonte, para manutenção do framework:
+
+```bash
+corepack pnpm install --frozen-lockfile
+corepack pnpm build
+node packages/cli/dist/index.js version
+```
+
+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.
+
+## Setup pelo CLI de lifecycle
+
+Faça primeiro um dry-run e revise conflitos:
+
+```bash
+zaip setup --workspace /caminho/do/projeto --dry-run --json
+zaip setup --workspace /caminho/do/projeto
+zaip doctor --workspace /caminho/do/projeto
+```
+
+O setup V2 cria ou valida:
+
+```text
+.agents/config/{project.yaml,framework.lock.yaml}
+.agents/rules/{core,workflow,architecture,security,context}.md
+.agents/requirements/{work-lifecycle,execution-engine,cost-observability,kanban-dashboard,context-engine,software-architecture}.md
+.agents/skills/
+.agents/records/{prds,specs,changes,tasks,executions,runs}/
+.agents/records/lifecycle/
+.local/claims/                 # claims idempotentes do lifecycle; não é histórico canônico
+```
+
+O runtime `.agents/runtime` usa a `.agents/` da raiz como fonte canônica das Rules, dos seis
+Requirements de área e das skills. Em uma instalação nova, o setup cria config e os seis diretórios
+vazios de data, projeta somente os arquivos portáveis do framework e registra a versão de origem em
+`source_release`. Histórico, Changes, Tasks, Runs e aliases específicos deste repositório nunca são
+copiados para o projeto consumidor.
+
+O setup identifica a propriedade pelo `framework.lock.yaml`: Rules presentes no lock pertencem ao
+framework; as demais são locais ao projeto e são preservadas em instalações e upgrades. Conflitos
+de ID ou contradições bloqueiam a operação; não existe override silencioso.
+
+Também gera adapters mínimos, como `AGENTS.md` e `CLAUDE.md`, sem sobrescrever conteúdo do usuário silenciosamente.
+
+## Migrar estado V1
+
+```bash
+zaip migrate plan --workspace /caminho/do/projeto --json
+zaip migrate plan --workspace /caminho/do/projeto --verbose --json
+zaip migrate apply --workspace /caminho/do/projeto --plan-hash HASH
+zaip migrate status --workspace /caminho/do/projeto
+```
+
+Por padrão, `plan` retorna somente fingerprint, contagens, findings e hash. `--verbose` acrescenta metadados e paths das operações, nunca payload base64. `apply` exige o hash revisado; uma reaplicação/retomada pode selecionar explicitamente `--migration ID`.
+
+A migração deve ser idempotente. Até ser aplicada e verificada, raízes V1 permanecem legado somente leitura. Para desfazer uma migração suportada:
+
+```bash
+zaip migrate rollback --workspace /caminho/do/projeto --migration ID
+```
+
+## Escolher a entrada certa
+
+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. 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).
+
+## Task-first
+
+Crie o draft manual, prepare e execute explicitamente:
+
+```bash
+zaip task create --title "Ajuste pontual" --short-name ajuste-pontual --objective "Resultado esperado" --requirements REQ-ID --acceptance AC-ID --write-scopes src/**
+zaip task prepare TASK-ID
+zaip task execute TASK-ID
+```
+
+Task-first não cria PRD nem SPEC sintéticas. `create` persiste somente a Task `draft`; `prepare` persiste o plano na Task; `execute` materializa Change e Execution rastreáveis antes da mutação. O prepare automático acima só aceita Task sem `depends_on`.
+
+Task-first registra objetivo, Requirements e Acceptance Criteria sem ocupar artificialmente as
+colunas Definição ou Planejamento. Uma Task criada ou preparada, mas não iniciada, aparece em Pronto
+para executar. Em pedidos diretos de ação, Change, Execution, Task e Run raiz são materializados
+antes da primeira mutação. Verificação e evidências sempre refletem registros reais.
+
+Para uma Task manual com dependências, modele a DAG completa em um draft de plano e gere o contrato canônico antes do prepare:
+
+```bash
+zaip plan build --draft ./task-plan-draft.json --output ./task-plan.json
+zaip plan validate --plan ./task-plan.json
+zaip task prepare TASK-ID --plan ./task-plan.json
+zaip task execute TASK-ID
+```
+
+O draft fornecido a `plan build` contém origem, Changes, Tasks, Execution, Requirements/AC e locks,
+mas não precisa calcular hash ou ordem topológica. Toda Task referenciada por `depends_on` precisa
+estar no mesmo plano. `plan validate` verifica o PreparedPlan completo sem materializá-lo.
+
+## SPEC opcional
+
+```bash
+zaip spec create --title "Objetivo técnico" --short-name objetivo-tecnico --objective "Resultado esperado"
+zaip spec prepare SPEC-ID --plan ./spec-plan.json
+zaip spec show SPEC-ID
+zaip spec execute SPEC-ID
+```
+
+`prepare` persiste IDs e DAG validada, sem criar Tasks. `execute` materializa a DAG de modo idempotente. A visão macro da SPEC agrega Tasks, Executions, Runs, evidências, retrabalho, tokens e custo.
+
+## PRD opcional
+
+```bash
+zaip prd create --title "Resultado de negócio" --short-name resultado-negocio --problem "Problema a resolver"
+zaip spec create --prd PRD-ID --title "Entrega técnica" --short-name entrega-tecnica --objective "Resultado técnico"
+zaip prd prepare PRD-ID --plan ./prd-plan.json
+zaip prd show PRD-ID
+zaip prd execute PRD-ID
+```
+
+É válido manter vários PRDs em rascunho, refinar alguns e executar somente os selecionados. `prepare`, `execute` e `deliver` bloqueiam PRD sem ao menos uma SPEC filha e qualquer Change do plano sem `spec_id`; o plano global inclui todas as Tasks e dependências selecionadas. `deliver` avalia somente as SPECs selecionadas no PreparedPlan do PRD, portanto outras SPECs filhas ainda em draft não bloqueiam a entrega.
+
+Na criação assistida, “me ajude a pensar” permanece Conversation. “Crie um PRD” faz até cinco perguntas críticas por turno e no máximo três turnos, depois persiste PRD/SPECs/PreparedPlan `draft` e registra decisões delegáveis da IA. Use uma SPEC por padrão; novas SPECs só representam capacidades independentes e paralelizáveis, sem arestas cross-SPEC. Blueprints compactos ficam visíveis antes do `ready`, mas Tasks/Changes/Execution só são materializadas quando o usuário pede “deixe/coloque em Pronto para Executar”, “finalize/conclua esse PRD” em `draft`, ou `execute`. A Run e o `creation_run_id` ficam vinculados ao macro; duração, tokens e custo só são agregados quando observados ou reconciliados e nunca são inventados quando indisponíveis.
+
+`execute` respeita Task, SPEC ou PRD conforme o menor grão nomeado. `implemente` sem alvo abre apenas uma Conversation de planejamento, em `draft` finaliza o plano, em `ready` executa e em estados ativos/falhos continua, retoma ou cria rework. `desenvolva|melhore|aprimore` nunca executa automaticamente. PRD cancelado gera sucessor `draft` com tag `rework` e vínculo ao registro imutável.
+
+## Refinar sem executar
+
+Não existe comando `refine`. Enquanto PRD, SPEC ou Task estiver em `draft`, edite seu Markdown
+canônico em `.agents/records`, incremente `revision` e atualize `updated_at`; em seguida use `show` e
+os validadores aplicáveis. Depois de `prepare`, não altere o plano silenciosamente: volte a um
+draft por uma transição explicitamente suportada pela política da entidade ou cancele e crie um
+novo draft. Isso preserva hash, auditoria e leitura humana.
+
+Para coleções grandes, use listagens compactas: `--status`, `--from`, `--to`, `--prd`, `--spec`, `--task`, `--limit` e `--after`. O padrão retorna no máximo 50 itens; `--all` é explícito.
+
+## Executar e acompanhar a DAG
+
+```bash
+zaip execution list
+zaip execution show EXEC-ID
+zaip execution start EXEC-ID
+zaip task next
+zaip task start TASK-ID
+zaip run start --short-name orquestrar-task --phase execution --run-purpose orchestration --entrypoint task --work-type new --client codex --agent zaip-agent-orchestrator --model MODEL --reasoning-effort EFFORT --conversation CONV-ID --execution EXEC-ID --task TASK-ID --change CHG-ID
+# execute e verifique o trabalho
+zaip run start --short-name finalizar-execution --phase execution --run-purpose finalization --entrypoint task --work-type new --client codex-subagent --agent zaip-agent-finalizer --model MODEL --reasoning-effort EFFORT --conversation CONV-ID --parent RUN-RAIZ-ID --execution EXEC-ID --task TASK-ID --change CHG-ID
+zaip run finish RUN-FINALIZADOR-ID --status completed
+zaip run finish RUN-ID --status completed --task-outcome completed --summary "Resultado" --evidence EVD-ID --changed-files src/arquivo.ts
+zaip run closure RUN-ID
+```
+
+Tasks `planned` cujas dependências estejam concluídas podem rodar em paralelo. Declare conflitos de arquivos, módulos, migrations, recursos ou ambientes como bloqueios da DAG; paralelismo não deve depender apenas de pertencerem a SPECs diferentes.
+
+Cada Run raiz representa a orquestração de uma Execution. Seus filhos são Sub-Runs: ao menos um executor elegível vem do catálogo, e o último deve ser `zaip-agent-finalizer`; ele só inicia depois dos demais descendentes e impede novos filhos. A CLI aplica sua decisão como `completed`, `blocked`, `failed` ou `cancelled`; finalizador ausente ou falho produz `blocked`. `executing` e `verifying` nunca são estados válidos depois do término da Run raiz. Uma Task bloqueada continua pela mesma identidade com `task resume`. Uma Task falhada exige `task rework`, preserva a identidade e incrementa a tentativa. Tasks concluídas ou canceladas são imutáveis.
+
+### Assurance e autonomia
+
+Ative a garantia tipada sem ativar execução por provider:
+
+```yaml
+execution:
+  runtime: manual
+assurance:
+  version: 1
+  standard_depth: auto
+  require_final_commit: true
+```
+
+Task standalone `lite` exige no mínimo uma validação e uma Evidence — normalmente uma de cada, sem rejeitar provas extras legítimas. `standard` exige duas ou três validações conforme o `verification_scope` persistido e pelo menos uma Evidence consolidada; registros históricos sem esse sinal usam o fallback conservador de write scopes. `critical` exige três ou mais, revisão independente e os controles acionados pelos sinais de risco persistidos. SPEC/PRD exigem ainda três validações e três Evidences parentais, matriz completa, integração e review independente. Para o runtime autônomo, configuração, controles e estratégia econômica, veja [Assurance adaptativa e autonomia opt-in](19-assurance-e-autonomia.md).
+
+## Changes, decisões e evidências
+
+Cada alteração possui `.agents/records/changes/YYYY/MM/CHG-.../change.md`, criado antes da primeira mutação. Ele registra:
+
+- plano e Requirement deltas;
+- implementação;
+- decisões humanas e da IA;
+- evidências por Acceptance Criterion;
+- evals e testes;
+- resultado final.
+
+Cada teste, revisão, eval ou check executado também deve gerar um artefato reproduzível em
+`artifacts/tests/`, `artifacts/evals/` ou `artifacts/checks/`. O registro inclui ao menos
+`executed_at` com timezone, comando, status, Task, Run e Acceptance Criteria cobertos. Quando uma
+verificação não se aplica, registre `status: not_applicable` e a justificativa; ausência de registro
+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
+
+Uma Execution é `interaction` para conversa sem Task artificial ou `delivery` para trabalho materializado; esta última coordena a DAG quando existir. Run é a chamada raiz do `zaip-agent-orchestrator` e possui `parent_run_id: null`; Sub-Run é cada chamada de subagente e possui `parent_run_id`. Ambas usam o ledger `RUN-*`, fixam modelo e effort e podem conter várias Calls, ferramentas e segmentos de uso. `run_purpose` distingue orquestração, execução, revisão, auditoria e finalização. Calls permanecem internas e suas quantidades, tokens e custos aparecem agregados na Run/Sub-Run.
+
+Operação oferece Trabalho (Kanban) e Trabalho (Lista), ambas com os filtros Todas as Tarefas, Visão Unificada Geral, PRDs, SPECs e Tarefas Avulsas. A lista mostra status, origem, Runs, Sub-Runs, duração, tokens, custo e cobertura. Operação e Monitor de Custos apresentam Runs e Sub-Runs separadamente. Cada Execution agrega contagens de Runs, Sub-Runs, finalizadores, Tasks finalizadas e Calls conhecidas sem dupla contagem; telemetria incompleta aparece como parcial. Cada segmento de uso é atribuído uma única vez; correções de duplicidade usam supersessão sem apagar o histórico.
+
+A captura do Codex persiste primeiro um envelope sanitizado em
+`.local/codex-telemetry-spool/v1/`, que permanece fora do Git. Depois do terminal da
+invocação, a compactação produz um `InvocationSummary` e publica chunks e manifestos por
+ano/mês/writer em `.agents/records/telemetry/`. Prompts, respostas, reasoning privado e segredos não
+entram nesses arquivos.
+
+Quando o Monitor de Custos recebe `from` e `to`, ele valida hashes e consulta os manifestos antes de
+carregar somente os chunks compatíveis com o período e os filtros. Na ausência de summaries
+aplicáveis, usa a projeção de Run existente sem promover a cobertura. O contrato completo, a
+semântica de `complete|partial|unavailable` e o procedimento de recuperação estão em
+[Telemetria Git-native do Codex](27-telemetria-git-native.md).
+
+O status técnico do Run (`completed`, `failed` ou `cancelled`) é separado do resultado da Task (`completed`, `blocked`, `failed` ou `cancelled`). Assim, um Run pode concluir tecnicamente e bloquear a Task porque um gate não passou. `execution` começa quando uma tentativa explícita se inicia, mesmo sem diff; `changed_files` e `result` registram se houve mutação.
+
+```bash
+zaip run start --short-name exemplo --phase execution --run-purpose orchestration --entrypoint task --work-type new --client codex --agent zaip-agent-orchestrator --model MODEL --reasoning-effort EFFORT --conversation CONV-ID --execution EXEC-ID --task TASK-ID --change CHG-ID
+zaip run usage RUN-ID --input-tokens N --output-tokens N
+zaip run finish RUN-ID --status completed --task-outcome completed --summary "Resultado" --evidence EVD-ID --changed-files src/arquivo.ts
+zaip run closure RUN-ID
+zaip run show RUN-ID
+zaip run list --phase execution --task TASK-ID --limit 50
+zaip run aggregate --prd PRD-ID --from 2026-07-01 --to 2026-07-31
+```
+
+`run-v2` permanece alias compatível. `run list` retorna resumos compactos e paginados; combine
+`--phase`, `--entrypoint`, `--work-type`, `--conversation`, `--execution`, `--change`, `--task`,
+`--spec`, `--prd`, período e paginação. `run aggregate` usa os mesmos filtros para totalizar uso,
+custo e cobertura sem dupla contagem. Valores ausentes permanecem nulos; dashboards mostram
+cobertura para impedir que custo desconhecido pareça custo zero.
+
+Reconciliação global não roda ao abrir o dashboard, a cada turno ou em intervalo. Ela só é executada
+quando uma pessoa confirma o popup **Reconciliar** ou chama explicitamente
+`zaip run reconcile --open`. O reconciliador usa fatos locais: pode concluir uma Task com evento
+terminal exato; marca Run órfão depois da tolerância como falha técnica; transforma ausência de gates
+em bloqueio; e nunca infere cancelamento ou sucesso sem evidência.
+
+## Organizar frontend, backend e site
+
+Crie somente as superfícies usadas pelo projeto, mas preserve seus papéis:
+
+```text
+apps/frontend/       # UI do produto
+apps/backend/        # APIs e workers
+apps/site/           # landing page e site público independente
+modules/<area>/      # capacidades de negócio
+packages/<library>/  # bibliotecas técnicas
+tests/e2e/           # jornadas entre aplicações
+```
+
+A dependência aponta de `apps` para `modules` e destes para `packages`. O site público não importa
+o dashboard, não lê `.agents` e não acessa implementação privada do backend.
+
+O dashboard ZAIP é outra fronteira, em `.agents/dashboard`. Ele possui somente
+`apps/frontend`; o servidor loopback fica em `packages/local-runtime`, acompanhado dos módulos
+`operations`, `cost-monitor` e `traceability`, demais packages próprios e `tests/e2e`. Ele lê
+os manifests canônicos em `.agents/records/lifecycle` e abre os demais records apenas por ID. A única
+reparação global iniciada pela UI ocorre após confirmação explícita no popup Reconciliar e usa o
+comando canônico de reconciliação; não deve ser movido para o `apps/frontend` do produto
+nem publicado como `apps/site`.
+
+No repositório-fonte do ZAIP, o gate de tamanho é executado isoladamente com:
+
+```bash
+node scripts/validate-source-size.mjs
+```
+
+Arquivos com 401–800 linhas geram warning; arquivos com 801 ou mais geram erro. Código gerado,
+`dist`, vendor, `node_modules`, `.agents/records` e lockfiles são ignorados. Exceções temporárias
+existem apenas para legado não-dashboard, não podem crescer e precisam declarar responsável,
+motivo e expiração.
+
+## Contrato CLI e taxonomia publicados
+
+O lifecycle observável avança em uma única direção: `conversation → planning → execution`. Task,
+SPEC e PRD são entrypoints distintos; Change narra a mutação, Execution coordena a DAG e Run mede
+uma tentativa. O manifesto público do CLI cobre estas áreas e ações:
+
+```text
+zaip setup; zaip doctor
+zaip adapters build|check
+zaip context inventory|build|inspect
+zaip manifest rebuild|refresh|show|reconcile
+zaip verify --changed --risk lite|standard|critical
+zaip architecture validate; zaip cqrs validate; zaip modules validate; zaip profile validate
+zaip eval run
+zaip migrate plan|apply|status|rollback
+zaip plan build|validate|normalize
+zaip prd create|list|show|prepare|ready|execute|activate|deliver|block|fail|cancel
+zaip spec create|list|show|prepare|ready|execute|activate|deliver|block|fail|cancel
+zaip change list|show|start|resume|block|verify|complete|fail|cancel
+zaip task create|list|next|show|prepare|execute|start|resume|rework|block|verify|complete|fail|cancel
+zaip execution list|show|start|resume|pause|block|verify|complete|fail|cancel
+zaip conversation start|finish
+zaip subagent capture
+zaip run start|list|aggregate|usage|finish|closure|reconcile|show
+zaip decision list|show|record
+zaip generate; zaip guard diff; zaip ui; zaip version
+```
+
+`pnpm test:contract` impede drift entre este guia, o manifesto de comandos, versões de packages,
+runtime distribuído e o gate de tamanho. `pnpm test:e2e` executa primeiro esse contrato e depois o
+E2E do dashboard.
+
+## Validação
+
+```bash
+zaip adapters check
+zaip context inventory
+zaip architecture validate
+zaip modules validate
+zaip profile validate
+zaip cqrs validate
+zaip eval run
+```
+
+`modules validate` verifica fronteiras entre `apps`, `modules` e `packages`. `profile validate`
+verifica o contrato de stack declarado em `.agents/config/project.yaml`. CQRS é obrigatório apenas quando o escopo contém casos de uso, estado ou separação de
+commands/queries.
+
+No repositório-fonte, rode também `pnpm validate:skills` e `pnpm test:encoding` após alterar Rules, Requirements, skills ou documentação.

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

@@ -0,0 +1,46 @@
+# Contrato de telemetria do Monitor de Custos
+
+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 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 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 é 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 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 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
+
+Filtros preenchidos somente com data são inclusivos: a data inicial começa em `00:00:00.000Z` e a final termina em `23:59:59.999Z`. O card de custo da Visão geral recebe o mesmo conjunto ativo do Monitor de Custos; por isso card, tabela e total devem coincidir para o mesmo período e moeda.
+
+## Verificação operacional
+
+1. Backfill dos manifests lifecycle após alterar records ou reconciliação:
+
+   ```powershell
+   node packages/cli/dist/index.js manifest rebuild --confirm-full-scan --json
+   ```
+
+2. Execute as validações do módulo e dos artefatos publicados:
+
+   ```powershell
+   corepack pnpm --filter @zaip-ai/dashboard-cost-monitor typecheck
+   corepack pnpm --filter @zaip-ai/dashboard-cost-monitor test -- agent-groups.test.ts CostMonitorPage.test.tsx CostTables.test.ts build-cost-monitor-projection.test.ts
+   corepack pnpm release:artifacts
+   node scripts/validate-release-parity.mjs --release
+   ```
+
+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. 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

@@ -0,0 +1,74 @@
+# Fluxos e roteamento ZAIP-AIOS
+
+Este guia preserva a explicação operacional detalhada sem tornar a página inicial pesada ou dependente do renderizador Mermaid do GitHub. Os fluxos são texto versionado e pesquisável; os ciclos de lifecycle que precisam de leitura visual usam PNG estático.
+
+## Roteamento normal
+
+```text
+Entrada → classificar demanda → Dave (orquestrador)
+       → executor por capacidade → Nanda (review independente)
+       → Gui (finalizador, último agente) → resultado terminal
+```
+
+O executor é Leo para Task genérica, Rafa para trabalho técnico amplo ou o especialista cujo catálogo cobre a capacidade solicitada. Todos reportam a Dave; a sequência não significa que um trabalhador chama o próximo.
+
+## Loop de custo e qualidade
+
+```text
+Tentativa → gates e review
+  aprovado → finalizar
+  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
+
+```text
+Pergunta simples → resposta direta       Análise especializada → Interaction
+Mudança delimitada → Task-first          Problema de produto → PRD
+Definição técnica → SPEC                 Continuação → retomar foco
+Falha ou achado → rework                 Auditoria → audit
+Deploy ou push → Git-only
+```
+
+Para produto e planejamento técnico: ideia ou problema → Dave → Bia (PRD e critérios) → Rafa (SPEC e DAG) → validação de prontidão → materializar Tasks → executar DAG → Nanda → Gui. Refinamento de produto retorna a Bia e refinamento técnico retorna a Rafa.
+
+## Demanda crítica e os 23 agentes
+
+Uma demanda crítica pode envolver Bia ou Rafa no planejamento, e especialistas como Will (backend), Doug (frontend), Manu (design) e Dan (cloud) na execução. Dani integra branches quando necessário; Nanda revisa sempre. Luiz entra com segurança ou dados críticos e Ana com alto risco, release ou auditoria ampla. Gui permanece o último agente.
+
+O grafo unificado foi removido da página inicial: ele não representa uma chamada aos 23 agentes. Dave seleciona somente a menor combinação que cobre a capacidade requerida. A referência atual de responsabilidades está no [catálogo de agentes](18-catalogo-de-agentes.md).
+
+## Seleção de modelo e esforço
+
+```text
+Agente selecionado → papel e fase → sinais persistidos → criticidade
+  override válido de Execution/Task → validar capacidade do host → Agent Run imutável
+  sem override → política automática → validar capacidade do host → Agent Run imutável
+```
+
+Modelo considera papel, fase, complexidade, ambiguidade e transversalidade. Esforço considera criticidade, dificuldade de raciocínio e custo do erro. Assurance considera criticidade, impacto e rollback.
+
+## Orquestração de uma Task
+
+```text
+Task em execução → Orchestrator → Executor → Evidence e Decisions
+                  → Reviewer → Tests, Checks e Evals
+                  → Auditor (quando necessário) → Finalizer → resultado
+```
+
+O resultado pode ser concluído, bloqueado, falhado, cancelado ou exigir rework. Bloqueio e rework iniciam um novo ciclo controlado; cancelamento é uma decisão humana explícita. O finalizador fecha a Run somente depois da revisão e de qualquer auditoria exigida.
+
+## Lifecycle e operação
+
+O caminho de sucesso é Definição → Planejamento → Pronto para Executar → Execução → Verificação → Concluído. Bloqueado, Falhado e Cancelado são saídas alternativas. Conversation usa uma Execution `interaction`; Task direta inicia imediatamente; Task preparada espera `execute`; SPEC coordena Tasks; PRD coordena SPECs selecionadas.
+
+![Lifecycles de Task, SPEC e PRD](assets/diagrams/lifecycles-task-spec-prd.png)
+
+Para os contratos completos e comandos de lifecycle, consulte [28-lifecycle-completo.md](28-lifecycle-completo.md).