@zaip-ai/cli 1.0.7 → 1.3.0

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

@@ -0,0 +1,167 @@
+# Telemetria Git-native do Codex
+
+Este documento descreve o comportamento implementado da telemetria do Codex no ZAIP-AIOS. O
+objetivo é preservar métricas auditáveis por invocação de agente sem versionar prompts, respostas,
+reasoning privado, segredos ou o fluxo completo de microeventos.
+
+O caminho implementado possui quatro camadas:
+
+1. captura sanitizada e durável em spool local;
+2. compactação em um resumo por invocação de agente;
+3. chunks e manifestos mensais rastreados pelo Git;
+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.
+
+## Fluxo dos dados
+
+```text
+evento observável do Codex
+        │
+        ▼
+spool local sanitizado e ignorado pelo Git
+.local/codex-telemetry-spool/v1/
+        │
+        ▼
+InvocationSummaryV1 por agent_invocation_id
+        │
+        ▼
+.agents/records/telemetry/<ano>/<mês>/writers/<writer-id>/
+├── chunks/<sha256>.jsonl
+└── manifest.json
+        │
+        ▼
+GET /api/v2/cost-monitor?from=...&to=...
+        │
+        ├── manifestos e chunks válidos: métricas manifest-first
+        └── ausência de resumo aplicável: campos de lifecycle preservados com cobertura explícita
+```
+
+### Captura
+
+O coletor aceita notificações sanitizadas do app-server do Codex quando elas são fornecidas ao
+comando `run usage` por `--codex-app-server-events`. A opção `--disable-codex-raw` desativa essa
+entrada e usa explicitamente o fallback de sessão local.
+
+O fallback correlaciona uma sessão somente quando existe vínculo observável com a Run. Para Runs do
+Codex, o `client_turn_id` é a chave canônica; para subagentes, o vínculo usa o `agent_path` e o turn
+filho observado. Uma relação pertencente a outro `agent_invocation_id` é conflito de ownership, não
+uma oportunidade para aproximar timestamps ou nomes.
+
+Cada evento do spool:
+
+- possui `source_event_key` estável, ID derivado e checksum SHA-256;
+- referencia Run, invocação, raiz, pai e ancestrais de lifecycle conhecidos;
+- limita o envelope sanitizado a 64 KiB;
+- persiste tokens, modelo, provider, tier, effort, status e timestamps somente quando observados;
+- registra contadores de conteúdo descartado;
+- não persiste prompt, texto de resposta, reasoning privado nem valores secretos.
+
+Eventos sem correlação suficiente permanecem em `unmatched/`; eles não são atribuídos por
+proximidade temporal. O spool continua sendo a fonte local de recuperação após a compactação e não
+deve ser apagado manualmente.
+
+### Compactação e ledger
+
+A compactação só produz um `InvocationSummaryV1` para uma invocação que já possua evento terminal
+ou de erro. Uma repetição da mesma `source_event_key` reutiliza idempotentemente o evento quando o
+conteúdo e a ownership são compatíveis; conteúdo divergente é rejeitado como conflito. Correlação
+de lifecycle divergente também interrompe a compactação.
+
+Um resumo preserva:
+
+- `agent_invocation_id`, raiz, pai, profundidade e tipo de invocação;
+- IDs de Execution, Task, SPEC, PRD, Change e Run quando conhecidos;
+- agente ZAIP, fase, propósito e status;
+- quantidade de eventos de origem e `source_hash`;
+- `llm_call_count` quando observável;
+- duração, latência e atraso de captura;
+- segmentos separados por provider, modelo, service tier, reasoning effort, cobertura e snapshot de
+  custo histórico;
+- `summary_hash` determinístico.
+
+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`.
+
+### Chunks e manifestos
+
+Cada workspace recebe um `writer-id` aleatório persistido somente em
+`.local/telemetry-writer-id.json`. Isso separa autores e worktrees e reduz conflitos
+em um manifesto global compartilhado.
+
+Os summaries de cada mês são ordenados e escritos em chunk imutável endereçado pelo hash do
+conteúdo. Uma repetição pode reutilizar o mesmo caminho somente se o conteúdo for byte a byte
+idêntico. O `manifest.json` do writer contém:
+
+- período, intervalo e quantidade de summaries;
+- hashes dos summaries e do manifesto;
+- cobertura `complete`, `partial` e `unavailable`;
+- métricas com `known_sum`, `unknown_count`, `total_count`, `complete` e `coverage_ratio`;
+- dimensões disponíveis para selecionar chunks;
+- timestamp mais recente da fonte e atraso máximo conhecido.
+
+Manifestos são read models reconstruíveis; os summaries nos chunks e o spool local preservado são
+as entradas para recuperação. Não edite chunks ou hashes manualmente.
+
+## Leitura no Dashboard
+
+O endpoint local `GET /api/v2/cost-monitor` ativa a leitura manifest-first somente quando recebe
+`from` e `to`. Os filtros `provider`, `model`, `agent`, `phase` e `status` são usados para eliminar
+chunks incompatíveis antes da leitura. O leitor valida:
+
+- período e estrutura do manifesto;
+- `manifest_hash`;
+- hash SHA-256 de cada chunk;
+- `summary_hash` de cada resumo;
+- unicidade por `agent_invocation_id`.
+
+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
+a cobertura disponível; não lê nem recria uma projeção ou arquivo local, e nunca promove a cobertura
+para `complete`.
+
+## Semântica de cobertura
+
+| Valor | Significado |
+| --- | --- |
+| `complete` | Todos os componentes exigidos para aquela métrica foram observados na fonte aceita. |
+| `partial` | Existe medição útil, mas pelo menos uma parte ou fonte exigida não está coberta. |
+| `unavailable` | A fonte não forneceu a métrica ou ela não pôde ser correlacionada com segurança. |
+
+Cobertura é calculada por dimensão. Uma invocação pode, por exemplo, ter duração conhecida e tokens
+indisponíveis. Por isso:
+
+- `known_sum` soma somente valores conhecidos;
+- `unknown_count` permanece visível;
+- `coverage_ratio` informa a fração comprovada;
+- `null` significa desconhecido e nunca é convertido em `0`;
+- “sem custo observado” não significa “custo zero”.
+
+## Operação e recuperação
+
+1. Não edite nem remova manualmente o spool, chunks, manifestos ou writer ID.
+2. Antes de diagnosticar custo, confirme a cobertura da métrica e o período consultado.
+3. Se um manifesto ou chunk falhar no hash, preserve os arquivos e execute diagnóstico; não
+   substitua o hash para fazer a leitura passar.
+4. Reprocesse somente a partir do spool sanitizado e das relações canônicas observadas. Não faça
+   backfill por vizinhança temporal para Runs que possuem `client_turn_id`.
+5. Mantenha `unavailable` quando a sessão original não oferece os dados necessários.
+6. Só promova o caminho novo amplamente após gates de cobertura, integridade e comparação
+   aprovados. Rollback de leitura preserva tanto o ledger novo quanto os records legados.
+
+Para validar alterações de mantenedor relacionadas a esse pipeline:
+
+```powershell
+corepack pnpm --filter @zaip-ai/decisions test
+corepack pnpm --filter @zaip-ai/costs test
+corepack pnpm --filter @zaip-ai/cli test
+corepack pnpm --filter @zaip-ai/dashboard-local-runtime test
+node scripts/validate-text-encoding.mjs
+```
+
+Os comandos acima são gates de desenvolvimento. A confirmação operacional continua sendo a
+combinação de hashes válidos, cobertura explícita e leitura do período real no Dashboard.

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

@@ -0,0 +1,144 @@
+# 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.
+
+## 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`.
+
+## Criação completa de PRD e SPEC
+
+“Me ajude a pensar” é Conversation. “Crie um PRD” revisa o prompt, faz até cinco perguntas críticas por turno durante no máximo três turnos e então persiste PRD `draft`, SPECs técnicas `draft` e PreparedPlan com blueprints de Tasks. Decisões delegáveis restantes são registradas como IA; autoridade externa/destrutiva, credenciais e riscos não delegáveis continuam bloqueantes.
+
+Use uma SPEC por padrão. Outra só existe quando pode ser implementada e verificada em paralelo contra contrato estável, sem depender de outra SPEC ou disputar write scopes. Dependências e ordem ficam entre Tasks da mesma SPEC.
+
+Antes de `ready`, blueprints aparecem apenas como lista compacta no PRD/SPEC; `prd create --plan` e `spec create --plan` validam o pacote antes da escrita, usam criação exclusiva por arquivo e rollback compensatório se uma etapa falhar, mas não prometem uma transação atômica multiarquivo contra interrupção abrupta. Não existem registros Task, Change ou Execution `delivery` nessa etapa. `prd create|rework|prepare` exige uma Run delegada da Bia (`zaip-agent-analyst`) e `spec create|rework|prepare` exige uma Run delegada do Rafa (`zaip-agent-builder`), sempre ativas e vinculadas ao turno raiz atual, com propósito `execution`. Em criação composta, `prd create --plan --run <bia-run> --spec-run <rafa-run>` exige duas Runs distintas sob o mesmo orquestrador: o PRD recebe a autoria da Bia e as SPECs recebem a autoria do Rafa. Replays históricos e identidades trocadas falham antes de escrever artefatos. Duração, tokens e custo são agregados quando observados ou reconciliados e permanecem `null` quando indisponíveis. `ready` materializa Tasks/Changes/Execution como `planned` em operação idempotente; `execute` inicia o menor grão nomeado.
+
+| Entrada | Quando usar | Cria Task? | Estado inicial visível |
+| --- | --- | --- | --- |
+| Conversation | Pergunta, feedback, status ou análise pontual read-only; cria Execution `interaction` | Não | Sem card |
+| Task avulsa executável | Pedido direto de alteração ou resultado independente | Sim | Execução antes da primeira mutação |
+| Task avulsa preparada | Pedido explícito de planejamento sem autorização de executar | Sim | Pronto para Executar |
+| SPEC | Entrega técnica com múltiplos blueprints ou DAG | Tasks em `ready|execute` | Planejamento enquanto `draft` |
+| PRD | Definição de produto organizada em SPECs independentes | Tasks em `ready|execute` | Definição enquanto `draft` |
+
+Conversa de análise nunca altera código, documentação ou configuração. A criação ou o refinamento explícito de PRD/SPEC `draft` é a única exceção de definição: a Execution `interaction` pode persistir o macro e seu PreparedPlan sem Task, Change ou Execution `delivery`. Fora dessa exceção, qualquer mutação persistente intencional exige Task materializada e Run raiz de orquestração ativa antes da escrita.
+
+São isentos apenas deploy/publicação Git sem mudança de produto, manifests e telemetria ZAIP gerados pelo lifecycle, metadados `.git`, caches, builds, testes e arquivos temporários descartáveis. Editar fontes ou documentação do ZAIP não é isento.
+
+## Colunas do Kanban
+
+| Coluna | Regra |
+| --- | --- |
+| Definição | Exclusiva de PRD `draft` |
+| Planejamento | Exclusiva de SPEC `draft` |
+| Pronto para Executar | PRD/SPEC `ready` e toda Task `planned` nunca iniciada ou tentada, avulsa ou vinculada a SPEC |
+| Execução | Task `executing`; SPEC/PRD `active` |
+| Verificação | Task `verifying` ou macro executando gates parentais |
+| Concluído | Task `completed` ou macro `delivered` |
+| Bloqueado | Resultado retomável com condição objetiva |
+| Falhado | Erro técnico impeditivo; exige rework |
+| Cancelado | Cancelamento humano explícito e imutável |
+
+Activity local nunca prevalece sobre um status final persistido. Uma invocação obsoleta não pode reviver Task concluída, bloqueada, falhada ou cancelada.
+
+## Trabalho, Execution, Run, Sub-Run e Call
+
+As cinco camadas possuem responsabilidades diferentes:
+
+| Camada | Responsabilidade |
+| --- | --- |
+| Trabalho | Task, SPEC ou PRD que descreve o resultado e seu lifecycle |
+| Execution | `interaction` registra uma conversa; `delivery` coordena Task, Change e DAG quando aplicável |
+| Run | Chamada raiz do `zaip-agent-orchestrator`; possui `parent_run_id: null` |
+| Sub-Run | Chamada de subagente feita dentro da Run; possui `parent_run_id` |
+| Call | Invocação interna de modelo LLM; herda a configuração da Run/Sub-Run |
+
+Run e Sub-Run compartilham o mesmo ledger canônico `RUN-*`; a distinção é derivada de `parent_run_id`, sem entidade duplicada. `run_role` usa somente `intake`, `orchestrator` ou `subagent`; valores históricos `owner` e `contributor` são aceitos apenas na leitura e normalizados imediatamente. `run_purpose` informa se a chamada executa `orchestration`, `execution`, `review`, `audit` ou `finalization`.
+
+Cada Run/Sub-Run fixa agente, modelo e effort até terminar. Mudança deliberada de agente, modelo, effort ou fase material abre outra chamada de agente; retry técnico preserva a configuração corrente. Calls podem ser várias dentro da mesma chamada de agente e não possuem lifecycle nem tela própria.
+
+Quando o host expõe Calls, a Run/Sub-Run agrega quantidade conhecida, terminais, falhas, cancelamentos, configuração efetiva, tokens e custo. Ausência de telemetria permanece `null`; nunca se presume zero e nunca se cria `CallProjection`.
+
+### Barreira do finalizador
+
+Cada Execution usa uma Run raiz do `zaip-agent-orchestrator`. 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`.
+
+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`.
+
+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.
+
+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.
+
+Exemplo:
+
+```bash
+zaip run finish RUN-ID \
+  --status completed \
+  --task-outcome blocked \
+  --summary "Gate de integração pendente"
+zaip run closure RUN-ID
+```
+
+## Fechamento e retomada de Tasks
+
+Antes de uma Run raiz terminar, sua Task deve estar em um destes estados:
+
+- `completed`: resultado e gates aprovados;
+- `blocked`: inconclusão retomável, dependência externa ou gate insuficiente;
+- `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.
+
+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`.
+
+## Agregação de SPEC e PRD
+
+Quando a primeira Task filha inicia, SPEC e PRD relacionados passam para `active` e permanecem em Execução enquanto restar trabalho macro, inclusive entre Runs. O resultado isolado de uma Task não terminaliza o pai.
+
+- 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.
+
+## 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 algoritmo é idempotente e conservador:
+
+- `task_complete` local exato permite finalizar tecnicamente a Run e tentar os gates;
+- gate insuficiente produz `blocked`, nunca sucesso inventado;
+- Run sem invocação ativa por dez minutos é órfã e termina como `failed`;
+- `cancelled` nunca é inferido;
+- Tasks apenas prontas, sem Run terminal atribuída, não são reavaliadas como travadas.
+
+O hook pre-write é diferente da reconciliação: ele verifica localmente se o turno atual possui Run raiz e Task em execução antes de permitir mutação. Essa checagem não chama modelo, não consome tokens e não percorre o backlog.
+
+## Projeção no dashboard
+
+Em Operação e Monitor de Custos, “Chamadas do agente orquestrador” e “Chamadas de subagentes” possuem filtros separados. A tabela de Executions agrega, sem dupla contagem, Runs de orquestrador, Sub-Runs, Sub-Runs finalizadores, Tasks finalizadas e Calls de LLM conhecidas. Quando nem todas as Calls são observáveis, a contagem é marcada como parcial em vez de assumir zero.
+
+Trabalho possui duas leituras da mesma projeção: Trabalho (Kanban), por estágio, e Trabalho (Lista), tabular. As duas mantêm os filtros Todas as Tarefas, Visão Unificada Geral, PRDs, SPECs e Tarefas Avulsas. A lista expõe indicadores operacionais por item, incluindo status, origem, Runs, Sub-Runs, duração, tokens, custo e cobertura.
+
+Cada segmento de telemetria possui uma chave de origem e só pode ser atribuído uma vez. Correções de duplicidade preservam o evento histórico e registram uma supersessão; projeções nunca devem somar os dois eventos.
+
+## Persistência compacta da telemetria
+
+Microeventos observáveis do Codex são sanitizados e gravados primeiro no spool local ignorado pelo
+Git. Depois de um terminal ou erro, eles são compactados em um `InvocationSummaryV1` por invocação
+de agente. Os summaries são organizados em chunks imutáveis e manifestos mensais por writer em
+`.agents/records/telemetry/<ano>/<mês>/writers/<writer-id>/`.
+
+Essa compactação não substitui o ledger `RUN-*`: a Run continua sendo a fonte de lifecycle,
+atribuição e evidência. O summary é a fonte compacta de métricas observadas. O Dashboard combina as
+duas leituras sem dupla contagem; tokens e custos do summary são autoritativos quando válidos, mas
+uma duração delimitada do lifecycle é preservada se a fonte compacta não conhece a duração.
+
+Cobertura é independente por métrica. Tokens, Calls, custo, duração e latência podem ter estados
+diferentes na mesma invocação. `known_sum`, `unknown_count` e `coverage_ratio` precisam viajar
+juntos; `null` nunca é normalizado para zero. Detalhes de armazenamento, integridade, fallback e
+recuperação estão em [Telemetria Git-native do Codex](27-telemetria-git-native.md).