@zaip-ai/cli 1.0.8 → 1.3.1

package/templates/.agents/dashboard/apps/frontend/dist/assets/DashboardHelpDialog-BgVgrfhQ.js

@@ -0,0 +1,2310 @@
+import{S as e,b as t}from"./cost-monitor-DKwP1stV.js";import{t as n}from"./dashboard-localization-CLJ0lT9v.js";var r=`# Primeiros passos
+
+1. Leia \`.agents/config/project.yaml\` e \`.agents/rules/core.md\`.
+2. Consulte \`.agents/records/lifecycle/\` para descobrir o estado atual pelos manifests canônicos.
+3. Classifique a entrada: Conversation, Task avulsa, SPEC ou PRD. Pergunta/análise read-only é Conversation e não cria Task.
+4. Carregue somente Rules, Requirements e skills aplicaveis.
+5. Defina aceite verificavel antes de editar.
+6. Antes de escrita persistente, inicie Task, Change, Execution e Run raiz do orquestrador; execute Sub-Runs, teste e registre evidencias no ciclo de vida ativo.
+
+Evite varrer \`.agents/records/\`: abra um record apenas quando possuir seu ID.
+
+Para PRD/SPEC, diferencie conversa de criação: “me ajude a pensar” não cria artefato; “crie” persiste o pacote \`draft\` completo e sua telemetria. Faça até cinco perguntas críticas por turno, no máximo três turnos; depois registre decisões delegáveis da IA. Tasks reais só nascem em \`ready|execute\`.
+`,i=`# Requirements
+
+Use Requirement para uma obrigacao duravel e testavel.
+
+1. Descreva resultado e limite, nao a implementacao preferida.
+2. Crie criterios de aceite observaveis.
+3. Registre riscos, dependencias e casos negativos.
+4. Relacione cada criterio a teste ou evidencia.
+5. Versione mudancas sem apagar a intencao anterior.
+6. Promova somente depois de validar consistencia e rastreabilidade.
+
+Um bom criterio responde inequivocamente: passou ou falhou?
+
+Para uma entrega nova ou retomada explicitamente, planeje também o cenário
+discriminante, ambiente e modalidade de observação por AC. O contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md)
+define estados, limites e o que ainda depende de revisão humana.
+`,a=`# Tasks
+
+Use Task para uma entrega pequena, independente e com um resultado claro.
+
+1. Pedido avulso explícito de ação entra diretamente em Execução; somente preparação sem autorização de executar pode parar em Pronto para Executar.
+2. Declare objetivo, escopo e fora de escopo.
+3. Vincule Requirements aplicaveis.
+4. Liste arquivos ou componentes provaveis, sem congelar a solucao.
+5. Defina verificacoes proporcionais ao risco.
+6. Use uma Run raiz do orquestrador por tentativa, finalize os Sub-Runs de trabalho e execute o finalizador como ultimo filho.
+7. Antes de a Run terminar, mova a Task para completed, blocked, failed ou cancelled; nunca deixe executing/verifying.
+8. Retome blocked com \`task resume\`; trate failed com \`task rework\` na mesma Task. Completed/cancelled sao imutaveis.
+
+Em PRD/SPEC \`draft\`, a lista visível vem dos blueprints do PreparedPlan e não representa Tasks materializadas. \`ready\` cria os registros \`planned\`. Execução pode ser pedida diretamente no menor grão Task, sem ampliar para toda a SPEC ou PRD.
+
+## Modelo, effort e velocidade
+
+Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex. A única forma suportada de executar trabalho de produto mais rápido é usar Fast manualmente em uma Task-first realmente independente; o ZAIP não ativa nem persiste essa seleção. Uma Task descendente de PRD ou SPEC segue a orquestração automática do pai e executa sempre com velocidade \`standard\`, mesmo quando for acionada no menor grão.
+`,o=`# SPECs
+
+Use SPEC quando a entrega exige varias Tasks ou uma ordem de dependencia.
+
+1. Transforme o resultado desejado em capacidades verificaveis. Faça até cinco perguntas críticas por turno e encerre esclarecimento em até três turnos.
+2. Consulte \`stack\` e \`stack.overrides\` em \`.agents/config/project.yaml\`; este arquivo contem a definicao tecnica canonica da stack do projeto.
+3. Registre \`stack_profile\`, \`stack_overrides\`, \`stack_description\` curta e componentes com linguagem, runtime, frameworks, versoes exatas e fontes verificaveis no workspace.
+4. Registre o blueprint técnico da SPEC e divida em blueprints de Tasks pequenas, cada uma com aceite próprio; \`spec create --plan\` persiste esse pacote em \`draft\` e registros Task só são criados em \`ready|execute\`.
+5. Modele dependencias como DAG; evite sequencias artificiais.
+6. Identifique caminhos criticos, riscos e rollback.
+7. Mapeie cada Requirement para Tasks e evidencias.
+8. Valide a SPEC antes de iniciar execucao; bloqueie stack ausente, divergente ou sem versoes exatas e fontes existentes.
+9. Ao iniciar a primeira Task, mantenha a SPEC em Execucao entre todas as Runs filhas; resultado terminal de uma Task nao terminaliza a SPEC.
+10. Depois de todas as Tasks concluidas, rode verificacao e Evidence parentais antes de deliver.
+
+Uma SPEC planeja a entrega; nao autoriza mudancas externas por si so.
+
+Use uma SPEC por padrão. Separe outra somente quando as capacidades puderem ser implementadas e verificadas em paralelo contra contratos estáveis, sem dependência ou write scope conflitante. Dependências e ordem ficam na DAG de Tasks da mesma SPEC.
+
+Toda Execution originada por SPEC usa velocidade \`standard\` em suas Tasks, Runs e Sub-Runs. A seleção manual de Fast no Codex não substitui essa política. Se uma necessidade urgente for realmente pequena e independente da DAG e dos gates parentais, ela pode ser tratada como Task-first com velocidade manual; não fragmente uma SPEC artificialmente apenas para executar mais rápido.
+`,s=`# PRDs
+
+Use PRD para uma iniciativa de produto com multiplas capacidades ou SPECs.
+
+1. Registre problema, publico, resultado e metricas.
+2. Delimite escopo, restricoes e nao objetivos.
+3. Mantenha o PRD agnostico de linguagem, framework, banco, infraestrutura e fornecedor; tecnologia imposta externamente entra como restricao de negocio, nao como desenho da solucao.
+4. Especifique requisitos funcionais e nao funcionais.
+5. Use uma SPEC por padrão. Crie outra somente para capacidade implementável e verificável em paralelo, sem dependência entre SPECs; dependências ficam nas Tasks internas.
+6. Relacione riscos, rollout, observabilidade e rollback.
+7. Monte a DAG e confirme que todo aceite possui evidencia planejada.
+8. Mantenha PRD e SPECs selecionadas em Execucao enquanto restar trabalho; Runs filhas fecham Tasks, nao o macro.
+9. Conclua somente depois das Tasks, integracao, outcomes e gates parentais.
+
+## Intenções
+
+- “Me ajude a pensar sobre um PRD”: Conversation, sem artefato.
+- “Crie um PRD”: até cinco perguntas críticas por turno e no máximo três turnos; depois persiste PRD, SPECs e PreparedPlan \`draft\`, vincula a Run e o \`creation_run_id\` ao macro e não cria Tasks reais. Duração, tokens e custo só são agregados quando observados ou reconciliados.
+- “Deixe pronto para executar” ou “finalize/conclua esse PRD” em \`draft\`: lapida, valida e materializa SPECs/Tasks/Changes/Execution como \`ready|planned\`, sem executar.
+- “Execute esse PRD”: executa todas as SPECs selecionadas. Pedido dirigido a SPEC ou Task usa o menor grão.
+- “Implemente”: sem alvo abre apenas uma Conversation de planejamento; em \`draft\` finaliza o plano; em \`ready\` executa; em \`active|blocked|failed\` continua, retoma ou cria rework.
+- “Desenvolva/melhore/aprimore”: sempre planeja/refina/rework e nunca executa automaticamente.
+
+PRD cancelado permanece imutável. Novo planejamento cria sucessor \`draft\`, tag \`rework\` e \`rework_of_prd_id\`.
+
+## Quantas SPECs criar
+
+| SPECs | Quando usar | Exemplo |
+| --- | --- | --- |
+| 1 | Padrão; há sequência, contrato em evolução ou dependência entre frentes. | Recuperação de senha completa em uma DAG. |
+| 2 | Duas capacidades paralelas contra contrato estável e escopos separados. | Web e Mobile contra API congelada. |
+| 3 | Três capacidades entregáveis isoladamente; integração fica no PRD. | Identidade, cobrança e notificações. |
+| 4 | Quatro adaptadores independentes, com ownership e diretórios distintos. | Adaptadores fiscais de quatro países. |
+| 5 | Exceção: cinco implementações simétricas do mesmo contrato validado. | Email, SMS, WhatsApp, Push e Inbox. |
+
+Qualquer dependência técnica entre duas frentes obriga reuni-las na mesma SPEC e expressar a ordem entre Tasks. Mais de cinco exige recortar o PRD ou registrar uma decisão de exceção.
+
+Toda Execution originada por PRD usa velocidade \`standard\` em todas as SPECs, Tasks, Runs e Sub-Runs descendentes. Não existe skill, hook ou override de Fast para esse fluxo. A única execução de produto mais rápida suportada é Task-first realmente independente, com Fast selecionado manualmente no Codex; uma urgência não autoriza remover a estrutura necessária de PRD/SPEC.
+`,c=`# Execucao
+
+1. Confirme Task, Change, Execution, aceite e Run raiz do orquestrador.
+2. Antes da primeira mutacao persistente, confirme Task executing e Run raiz ativa no turno atual.
+3. Inspecione o diff e preserve alteracoes alheias.
+4. Use Sub-Runs para cada subagente; a Run raiz aguarda todos os descendentes ativos.
+5. Implemente o menor incremento coerente e rode verificacoes focadas.
+6. Registre decisoes consequenciais, observações por AC, evidencias e desvios.
+7. Antes de encerrar, execute os gates finais aplicáveis, documente rollback,
+   produza o commit isolado quando houver mutação e persista Validation/Evidence
+   do candidato exato. Falta de prova permanece pendência.
+8. Depois dos demais descendentes e das provas, execute \`zaip-agent-finalizer\`
+   como último filho. Nenhum filho novo pode iniciar depois dele.
+9. Aplique a decisão terminal pela CLI: Task, Change e Execution; atualize os
+   manifests e finalize a Run raiz, separando status técnico e resultado da Task.
+
+Nao marque conclusao por esforco: conclua pelo resultado verificavel. Gate insuficiente ou finalizador ausente usa blocked; erro tecnico impeditivo usa failed; cancelamento exige pedido explicito.
+
+Quando a entrega requer observação, siga o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md):
+o registro descreve o resultado declarado e seus limites, mas não executa o
+procedimento nem aprova o AC sozinho.
+
+\`execute\` respeita o menor grão nomeado: Task executa um nó elegível; SPEC executa sua DAG; PRD executa todas as SPECs selecionadas. “Conclua a execução” ou “finalize a implementação” em trabalho ativo continua Tasks e gates, mas nunca força sucesso. “Desenvolva/melhore/aprimore” volta a planejamento/rework e exige nova promoção.
+
+## Modelo, effort e velocidade por origem
+
+- Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex.
+- Fast para execução de produto é suportado somente em Task-first realmente independente e deve ser selecionado manualmente no Codex.
+- Executions originadas por SPEC ou PRD usam sempre velocidade \`standard\`, inclusive em todas as Tasks, Runs e Sub-Runs descendentes.
+- O ZAIP não ativa, persiste ou herda Fast por skill, hook, PreparedPlan ou override de Execution.
+- Selecionar uma Task descendente como menor grão não a transforma em Task-first nem remove a velocidade \`standard\` herdada do macro.
+`,l=`# Revisao e validacao
+
+1. Revise Requirements e criterios de aceite.
+2. Examine diff, limites arquiteturais e caminhos de erro.
+3. Rode testes focados e depois gates completos aplicaveis.
+4. Verifique seguranca, compatibilidade, documentacao e rollback.
+5. Classifique achados por impacto e cite evidencia concreta.
+6. Registre o resultado sem alterar implementacao em uma revisao read-only.
+
+Para ACs que exigem observação, confira cenário, expectativa, resultado,
+candidato, ambiente, locators e limitações segundo o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
+\`confirmed\` pode complementar uma Evidence compatível, mas não substitui
+validação, revisão independente nem finalizador. \`pending\`, \`limited\`,
+\`failed\` e \`not_applicable\` não são aprovação.
+`,u=`# Contexto e tokens
+
+1. Comece por \`project.yaml\`, \`core.md\` e pelos manifests de \`.agents/records/lifecycle/\`.
+2. Carregue somente a Rule, Requirement ou skill acionada.
+3. Prefira indices, resumos e busca direcionada a arquivos completos.
+4. Abra records apenas por lifecycle ID conhecido.
+5. Resuma fatos estaveis; preserve texto literal apenas quando normativo.
+6. Remova do contexto resultados superados e detalhes nao acionaveis.
+
+Para tools, leia \`catalog.yaml\`, escolha um ID e abra somente seu manifesto.
+`,d=`# Agentes e squads
+
+O catalogo em \`.agents/config/agents/catalog.yaml\` e a fonte canonica para
+delegacao. Ele registra 23 agentes e 6 squads. Nomes exibidos, perfis e
+capacidades podem mudar; antes de delegar, consulte o registro atual em vez de
+memorizar uma lista ou inventar uma identidade.
+
+## Como escolher
+
+1. Quebre o trabalho em subtarefas concretas, independentes e verificaveis.
+2. Escolha pelo conjunto de \`capabilities\`, \`execution_eligibility\`, ferramentas
+   e \`write_scopes\` do catalogo, nao apenas pelo titulo do agente.
+3. Use apenas o \`codex_name\` e o \`codex_task_name\` exatos do registro. Nao use
+   \`default\`, \`worker\`, \`explorer\` ou nomes ad-hoc.
+4. Defina objetivo, escopo de escrita, entradas, criterio de aceite e formato de
+   retorno antes da delegacao.
+5. Nao atribua a dois agentes arquivos ou responsabilidades que conflitem.
+
+## Squads
+
+As seis squads coordenam contextos recorrentes: entrega critica, analise de
+produto, design e website, marca e marketing, growth e RevOps, e vendas e
+governanca. A squad e um roteador de capacidade; a delegacao continua usando o
+agente catalogado que satisfaz o trabalho concreto.
+
+## Execucao e fechamento
+
+Uma Execution de delivery precisa de ao menos um executor elegivel. O
+orquestrador coordena a DAG, preserva a separacao de telemetria entre raiz e
+Sub-Runs e captura metadados observados apos spawn e termino. Reviewer,
+auditor ou integrador so entram quando sua capacidade for necessaria.
+
+O ultimo filho e sempre \`zaip-agent-finalizer\`, depois que os demais
+descendentes terminaram. Ele nao reescreve evidencia: aplica uma decisao
+restrita baseada em testes, diffs e registros reais. O resultado so deve ser
+reportado apos a barreira de finalizacao estar satisfeita.
+
+## Boas praticas
+
+- Centralize decisoes arquiteturais e integracao no responsavel adequado.
+- Exija caminhos de evidencia e resultados de comandos, nao declaracoes de
+  conclusao.
+- Use paralelismo apenas quando reduzir o caminho critico sem elevar conflito.
+- Escale bloqueios de autoridade, credencial, seguranca ou escopo; nao suponha
+  permissao externa.
+`,f=`# Segurança dos perfis Codex ZAIP-AIOS
+
+## Visão geral
+
+O ZAIP-AIOS oferece dois perfis atuais:
+
+| Perfil | Filesystem nativo | Rede de comandos | Uso recomendado |
+| --- | --- | --- | --- |
+| \`zaip-aios-full-access\` | Escrita em \`C:\\\` inteiro no Windows, quando as permissões do sistema permitirem | Completa, todos os domínios | Default humano; evita prompt técnico do Codex para comandos, mas não cria autoridade para ações externas, destrutivas ou de publicação |
+| \`zaip-aios-security\` | Escrita na raiz física do repositório, incluindo \`.git\`, \`.agents\`, \`.codex\` e demais arquivos ocultos | Limitada a \`github.com\` | Opt-in de menor privilégio; reinicie o Codex após selecionar |
+
+A permissão nativa determina o que o processo tecnicamente consegue alcançar. Ela não
+substitui autorização do usuário, regras do repositório, hooks, skills ou controles do
+sistema operacional.
+
+\`approval_policy = "never"\` remove a confirmação técnica prévia do Codex para a
+execução de comandos dentro do perfil. Isso não é uma autorização de negócio ou
+de escopo: deploy, push/publicação, ações remotas, gastos, exclusões relevantes
+e mudanças fora do objetivo continuam exigindo pedido explícito do usuário no
+turno atual. Apps e MCPs podem manter seu próprio
+\`default_tools_approval_mode = "approve"\`; esse ajuste é independente da
+política de aprovação de comandos.
+
+## \`zaip-aios-security\`
+
+### Acesso concedido
+
+O perfil restrito concede:
+
+- leitura dos caminhos mínimos necessários para executar ferramentas;
+- escrita em \`~/.ssh\` para reparar a configuração e a identidade SSH local;
+- escrita na raiz física absoluta deste repositório;
+- escrita em todos os descendentes do workspace, incluindo \`.git\`, \`.agents\`, \`.codex\` e demais arquivos ocultos;
+- rede de comandos limitada a \`github.com\` para operações Git/SSH autorizadas.
+
+Exemplo da definição efetiva:
+
+\`\`\`toml
+default_permissions = "zaip-aios-security"
+
+[permissions.zaip-aios-security]
+description = "ZAIP workspace-only development with editable project control trees and GitHub-only command network access."
+
+[permissions.zaip-aios-security.filesystem]
+":minimal" = "read"
+"~/.ssh" = "write"
+
+[permissions.zaip-aios-security.filesystem."C:\\\\caminho\\\\absoluto\\\\do\\\\workspace"]
+"." = "write"
+".git" = "write"
+".agents" = "write"
+".codex" = "write"
+
+[permissions.zaip-aios-security.network]
+enabled = true
+mode = "limited"
+
+[permissions.zaip-aios-security.network.domains]
+"github.com" = "allow"
+\`\`\`
+
+A tabela usa a raiz física em vez de \`extends = ":workspace"\` ou \`:workspace_roots\`.
+No sandbox elevado do Windows, esses dois modos aplicam negações especiais a \`.agents\` e
+\`.codex\`; uma regra \`write\` mais específica pode não reabri-las por causa da precedência das
+ACLs \`DENY\`. As entradas explícitas acima materializam o conjunto correto de capabilities,
+mantêm a escrita limitada ao repositório — inclusive em \`.git\` — e não concedem escrita ao restante de \`C:\\\`, ao perfil do
+usuário, a outros repositórios ou ao sistema operacional.
+
+### Segurança adicional
+
+\`zaip-aios-security\` possui a proteção mais forte porque os limites principais são aplicados
+pelo sandbox nativo:
+
+- uma tentativa de escrita fora do workspace é negada mesmo que uma instrução ou ferramenta
+  peça essa operação;
+- comandos alcançam apenas \`github.com\`; outros destinos permanecem negados;
+- \`~/.ssh\` pode ser alterado por fluxos Git ou de configuração explicitamente autorizados;
+- o impacto máximo de uma edição comum fica contido no repositório;
+- todas as camadas ZAIP descritas abaixo continuam ativas.
+
+Esse perfil é a opção de menor privilégio recomendada quando o trabalho cabe no workspace,
+especialmente para revisão, testes e manutenção delimitada. O perfil humano continua sendo
+\`zaip-aios-full-access\`; selecione \`zaip-aios-security\` explicitamente quando desejar contenção
+nativa. A escrita em \`~/.ssh\` e o egress para \`github.com\` ampliam o impacto potencial; nunca
+altere chaves, credenciais ou remotos sem autorização explícita.
+
+## \`zaip-aios-full-access\`
+
+### Acesso concedido
+
+No Windows, o perfil de acesso completo concede escrita em \`C:\\\` inteiro e rede completa:
+
+\`\`\`toml
+default_permissions = "zaip-aios-full-access"
+
+[permissions.zaip-aios-full-access.filesystem]
+":root" = "write"
+
+[permissions.zaip-aios-full-access.network]
+enabled = true
+mode = "full"
+
+[permissions.zaip-aios-full-access.network.domains]
+"*" = "allow"
+\`\`\`
+
+A configuração pode representar a raiz como \`:root\` ou \`C:\\\\\`. Neste ambiente, isso
+inclui tecnicamente:
+
+- o workspace e todos os seus arquivos;
+- \`.agents\`, \`.codex\` e \`.git\`;
+- outros repositórios em \`C:\\\`;
+- o perfil do usuário e seus arquivos;
+- diretórios de aplicações e do sistema;
+- qualquer destino de rede alcançável pelo host.
+
+O acesso continua sujeito às ACLs do Windows, políticas corporativas, arquivos em uso e
+privilégios da conta. O perfil não transforma o processo em administrador nem garante
+alteração de todo arquivo.
+
+### Riscos residuais
+
+\`zaip-aios-full-access\` continua sendo um perfil de maior risco. Um comando incorreto,
+conteúdo malicioso, dependência comprometida ou erro de escopo pode tentar:
+
+- alterar ou excluir arquivos fora do projeto;
+- modificar outros repositórios;
+- acessar dados do usuário;
+- executar operações destrutivas no sistema;
+- enviar dados pela rede;
+- ampliar o impacto de uma falha de supply chain.
+
+Ele é o default humano de permissão nativa. \`approval_policy = "never"\` evita
+prompt técnico para comandos, mas não substitui autorização explícita para
+operações externas, destrutivas ou de publicação. O hook complementar permanece
+default-deny para operações externas e não torna este perfil equivalente ao restrito.
+
+## Camadas que reduzem o risco do full access
+
+O acesso completo é mitigado por defesa em profundidade, mas nenhuma camada torna
+\`zaip-aios-full-access\` equivalente ao perfil restrito:
+
+1. **Autorização explícita do usuário:** mudanças externas, destrutivas, publicação, deploy,
+   gasto e mutações remotas exigem pedido explícito no turno atual.
+2. **Escopo do repositório:** \`AGENTS.md\`, Rules e skills limitam o trabalho ao objetivo e
+   proíbem inferir autoridade adicional a partir do acesso técnico.
+3. **Hook \`PreToolUse\` ativo nos dois perfis:** valida comandos e patches antes da execução; bloqueia escapes do
+   repositório, referências diretas a segredos, elevação, persistência de sistema, firewall,
+   antivírus, serviços, Git destrutivo, banco destrutivo e clientes remotos não autorizados.
+4. **Regras \`forbidden\`:** arquivos em \`.codex/rules/\` negam classes perigosas de comandos
+   mesmo quando o sandbox permitiria executá-las.
+5. **Política GitHub delimitada:** deploy e push seguem preflight, branch e remoto explícitos;
+   force-push, exclusão remota e publicação não solicitada permanecem proibidos.
+6. **Proteção de segredos:** tokens, chaves privadas, credenciais e valores de ambiente não
+   podem ser impressos, copiados, registrados em Runs nem incluídos em commits.
+7. **Lifecycle e telemetria sanitizada:** Runs registram atribuição, uso e resultado sem
+   autorizar ações nem persistir segredos.
+8. **Subagentes com menor privilégio:** agentes de revisão e auditoria permanecem read-only;
+   builders e integradores recebem escopos limitados.
+9. **Controles do sistema operacional:** ACLs, conta Windows, arquivos em uso e políticas do
+   host continuam sendo a última barreira técnica.
+
+Essas camadas reduzem probabilidade e impacto, mas podem conter bugs ou lacunas. Os limites
+nativos de \`zaip-aios-security\` oferecem proteção adicional ao negar escrita fora do workspace
+e egress para destinos diferentes de \`github.com\` antes que a operação alcance o sistema ou a rede.
+
+## Proteções do candidato e limites
+
+O Dashboard é um serviço local: antes de criar a sessão ou atender rotas,
+aceita somente autoridades HTTP \`localhost\` e \`127.0.0.1\`, com porta válida.
+Hostnames arbitrários não recebem o cookie de bootstrap, mesmo que apontem
+para loopback. Isso complementa a sessão e as verificações de origem; não
+autoriza expor o serviço por proxy ou na rede pública.
+
+Na gravação de Validation, Evidence, Observation e eventos de Run, padrões
+conhecidos de credenciais são rejeitados com erro sanitizado. Isso inclui
+Bearer/Basic, chaves privadas, atribuições explícitas de senha/chave e URLs
+com credenciais ou parâmetros sensíveis. Valores sanitizados como
+\`[REDACTED]\` e métricas numéricas de tokens continuam aceitos. A proteção não
+é um scanner universal de segredos: sanitize o conteúdo antes de registrá-lo
+e não use o aceite do parser como prova de ausência de dados sensíveis.
+Leitura de histórico não o sanitiza nem altera retroativamente sua validade.
+
+Operações concorrentes de lock preservam a contenção física. Se uma entrada
+desaparecer durante a resolução no Windows, apenas \`ENOENT\` na entrada
+lógica permite subir ao pai e revalidá-lo. Symlink/junction existente fora
+da raiz e outros erros continuam bloqueando a escrita; não existe exceção
+por nome de diretório temporário do sistema.
+
+## Escolha do perfil
+
+Use \`zaip-aios-security\` quando:
+
+- todo o trabalho deve permanecer neste workspace;
+- \`.agents\` e \`.codex\` precisam ser editáveis;
+- comandos precisam, no máximo, alcançar \`github.com\` para operações Git/SSH autorizadas;
+- menor privilégio é desejado.
+
+Use \`zaip-aios-full-access\` como default humano quando:
+
+- for necessário corrigir a própria configuração de permissões;
+- uma operação autorizada precisar de um caminho fora do workspace;
+- o bloqueio do perfil restrito tiver sido diagnosticado e não houver alternativa limitada.
+
+Não use full access apenas para evitar investigar uma negação.
+
+## Validação obrigatória
+
+Após alterar qualquer perfil:
+
+1. Confirme que \`default_permissions\` seleciona exatamente o perfil desejado.
+2. Confirme que não existe \`sandbox_mode\` em outra configuração carregada.
+3. Reinicie completamente o Codex.
+4. Com \`zaip-aios-security\`, valide escrita no workspace, em \`.agents\` e em \`.codex\`.
+5. Quando uma operação Git estiver autorizada, confirme que \`.git\` aceita a alteração de índice necessária, sem ampliar o acesso fora do repositório.
+6. Confirme que escrita fora do workspace é negada sem criar arquivo externo.
+7. Confirme que Git/SSH alcança \`github.com\` somente após autorização de deploy e que outros destinos continuam negados.
+8. Execute uma captura ZAIP e confirme \`run.started\`, \`usage.recorded\` e \`run.finished\`.
+9. Com full access, confirme a seleção do perfil sem realizar probes destrutivos ou gravar em
+   caminhos externos apenas para demonstrar alcance.
+
+O sandbox e as ACLs são materializados na inicialização; o teste funcional precisa ocorrer
+em uma nova sessão.
+
+Se uma versão anterior com \`:workspace\` ou \`:workspace_roots\` já tiver sido executada e o
+reinício continuar negando \`.agents\`/\`.codex\`, feche todas as sessões Codex, faça backup de
+\`~/.codex/cap_sid\`, mova somente o arquivo ativo para fora desse caminho e reinicie o Codex.
+O runtime criará novos capability SIDs; os \`DENY\` antigos ficarão inertes por não pertencerem
+ao novo token. Não edite ACLs manualmente e preserve o backup para rollback.
+
+## Arquivos da política
+
+| Arquivo | Papel |
+| --- | --- |
+| \`~/.codex/config.toml\` | seleção e definição efetiva dos perfis |
+| \`.codex/config.toml\` | projeção versionada dos perfis e hooks |
+| \`.codex/zaip-aios-security.config.toml\` | configuração dedicada do perfil restrito |
+| \`.codex/zaip-aios-full-access.config.toml\` | configuração dedicada do perfil completo |
+| \`.agents/skills/zaip-skill-security/SKILL.md\` | avaliação dos riscos e controles |
+| \`.agents/skills/zaip-skill-setup/SKILL.md\` | instalação, correção e validação dos perfis |
+| \`.codex/hooks/zaip-pre-tool-use.mjs\` | guarda adicional de comandos |
+| \`.codex/rules/\` | decisões determinísticas de comandos permitidos e proibidos |
+| este guia | contrato operacional e comparação dos perfis |
+`,p="# Observabilidade e custos\n\n1. Selecione a Run pelo ID e confirme a fonte de cada métrica.\n2. Verifique duração, tokens, custo, retries e retrabalho, distinguindo observado, reconciliado e estimado.\n3. Compare aceite planejado com evidência produzida.\n4. Identifique gates lentos, contexto excessivo e chamadas repetidas.\n5. Agregue tendências sem expor prompts ou segredos sensíveis.\n6. Converta achados recorrentes em Rule, Requirement ou melhoria de skill.\n\nRun é o envelope da chamada do `zaip-agent-orchestrator`; `parent_run_id` nulo identifica esse nível. Sub-Run é a chamada de qualquer subagente e possui `parent_run_id`. Ambas podem agregar Calls, segmentos de uso, tokens e custo; Calls não possuem tela ou lifecycle próprio. A configuração solicitada de modelo e effort pertence à Run. Modelo, effort e tier efetivos só devem ser reportados quando vierem de evento/provider observado: defaults do catálogo, seleção planejada ou comportamento aparente não os comprovam. Operação e Monitor de Custos apresentam “Chamadas do agente orquestrador” e “Chamadas de subagentes”; a Execution soma as duas categorias, finalizadores e Calls sem dupla contagem. Cada segmento de uso possui uma chave de origem e só pode ser atribuído uma vez; uma correção de duplicidade registra supersessão e preserva o evento histórico. Inspecione `run_purpose`, pai e `agent_name`; agentes do catálogo usam `zaip-agent-*`. Diferencie status técnico da chamada de agente e resultado terminal da Task. Reconcilie lifecycle globalmente apenas por comando humano explícito ou pelo popup confirmado; isso não ocorre em cada turno nem ao abrir o dashboard.\n\nA criação explícita de PRD/SPEC vincula a Run de definição e o `creation_run_id` ao macro. Duração, tokens e custo aparecem no PRD/SPEC antes de existirem Tasks somente quando houver fonte capturada ou derivação identificada por proveniência. Um valor `estimated`, `legacy_inferred` ou `reconciled` não é dado observado e não comprova medição da chamada. Quando duração, tokens ou custo não foram capturados, eles permanecem explicitamente indisponíveis (`null`/`unavailable`); nunca atribua telemetria ausente nem transforme ausência em zero. Pensar sem criar permanece apenas em Conversas.\n",m=`# Instalacao e upgrade
+
+1. Verifique versao atual e estado limpo ou conscientemente preservado.
+2. Execute doctor/integrity antes da mudanca.
+3. Faça dry-run da instalacao, migracao ou upgrade.
+4. Revise arquivos gerenciados, publicos e preservados.
+5. Aplique, valide adapters e rode gates.
+6. Teste rollback e confirme a versao final.
+
+\`framework.lock.yaml\` e relevante neste fluxo; nao o carregue no trabalho comum.
+`,h=`# Boas praticas
+
+- Comece pelo resultado e aceite, nao pela ferramenta.
+- Mantenha dominio independente de infraestrutura.
+- Faça mudancas pequenas, reversiveis e rastreaveis.
+- Valide cedo com testes deterministas e focados.
+- Prefira configuracao explicita a convencoes ocultas.
+- Leia contexto sob demanda e preserve o budget de tokens.
+- Trate documentacao, observabilidade e rollback como parte da entrega.
+- Registre observação somente como resultado declarado e vinculado; ela não
+  executa comandos, não examina automaticamente telas e não aprova um AC.
+  Aplique o [contrato de prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
+- Nunca termine a Run raiz sem o Sub-Run finalizador ou com Task em executing/verifying.
+- Nao terminalize SPEC/PRD por causa do resultado isolado de uma Task filha.
+- Prefira reconciliacao manual sob demanda; hooks de escrita fazem checagem local sem varredura global.
+- Use uma SPEC por padrão; divida somente capacidades realmente independentes e paralelizáveis.
+- Não crie Tasks durante definição: mostre blueprints compactos e materialize somente em \`ready|execute\`.
+- Resolva verbos de lifecycle pelo alvo e status persistido, nunca por palavra isolada.
+`,g="# Troubleshooting\n\n1. Reproduza o problema com o menor comando possivel.\n2. Leia a mensagem completa e identifique o primeiro erro causal.\n3. Rode doctor, validadores focados e `git diff --check`.\n4. Confira versoes, paths, encoding, variaveis e arquivos gerenciados.\n5. Compare `manifest.json`, `summary.json`, índices e chunks de `records/lifecycle`, sem varrer records.\n6. Corrija a causa, repita a reproducao e depois os gates completos.\n\nSe uma Task estiver presa em executing/verifying, use o popup Reconciliar. O reparo aceita `task_complete` exato, marca Run orfa apos dez minutos como failed e usa blocked quando faltam gates; nunca infere cancelamento. Nao habilite reconciliacao automatica por turno ou na abertura do dashboard.\n\nSe o problema for de instalacao ou integridade, consulte `framework.lock.yaml`.\n\nSe “finalizar” tentou entregar um PRD `draft`, confira adapters/skills: o correto é lapidar e mover para `ready`. Se uma DAG nova cruza SPECs, una as capacidades em uma SPEC e mantenha a dependência entre suas Tasks. PRD cancelado não reabre; crie sucessor `rework`.\n",_="# Tools e setup do Codex\n\n1. Peça ao agente para listar ou ativar uma tool; ele usa `$zaip-skill-tool-setup`.\n2. A skill lê somente catálogo e manifesto aplicável.\n3. MCP confiável é registrado desabilitado em `.codex/config.toml` e validado antes da ativação.\n4. API sem MCP confiável aciona `$zaip-skill-api-to-mcp` para gerar um adaptador seguro.\n5. Secrets nunca são coladas no chat; nomes ficam em `.agents/.env.example` e valores em armazenamento local ignorado.\n6. Alterações de configuração devem ser reversíveis e preservar preferências existentes.\n\nAtive por padrão apenas integrações públicas, read-only e sem autenticação, como documentação oficial. Browser/Playwright deve ser opt-in do perfil de desenvolvimento, pois inicia processos e amplia a superfície operacional.\n\n## MCP local gerado de API\n\n1. Modele um `adapter.yaml` a partir de documentação oficial; use o exemplo da skill API-to-MCP.\n2. Execute `scaffold-local-mcp.mjs` para gerar `definition.json`, `server.mjs` e `cli.mjs`.\n3. Rode `node .agents/tools/servers/<id>/cli.mjs doctor`.\n4. Faça chamadas read-only com `cli.mjs call <tool> '<json>'`.\n5. Gere um preview do Codex com `configure-local-mcp.mjs <id>`.\n6. Revise e aplique com `--write`; use `--enable` somente quando o doctor estiver pronto.\n\nO servidor usa STDIO, não abre porta e não exige deploy. Escritas ficam bloqueadas sem aprovação e `ZAIP_ALLOW_MCP_WRITES=1`.\n\n## Documentacao OpenAI\n\nO perfil default habilita `openaiDeveloperDocs` em `.codex/config.toml`, sem credencial e em modo read-only. Perguntas sobre OpenAI API, modelos, SDKs, Codex ou MCP devem acionar `$zaip-skill-openai-docs`, pesquisar o MCP oficial e citar a pagina consultada.\n",v="# Lifecycle e reconciliacao\n\n## Entradas\n\n- Conversation: pergunta, feedback ou análise read-only; captura uma interaction e Run sem Task artificial.\n- Task avulsa: resultado independente. Pedido de acao entra em Execucao antes da primeira escrita; pedido apenas de preparacao pode parar em Pronto para Executar.\n- SPEC: planejamento tecnico de multiplas Tasks; draft fica em Planejamento.\n- PRD: definicao de produto; draft fica em Definicao.\n\nPensar/explorar PRD ou SPEC é Conversation. Criar explicitamente persiste macro, SPECs e PreparedPlan `draft`, atribui telemetria e mantém apenas blueprints de Tasks. `ready` é o único ponto que materializa Tasks/Changes/Execution sem iniciar; `execute` materializa e inicia.\n\n## Colunas\n\n| Coluna | Entidades |\n|---|---|\n| Definicao | somente PRD draft |\n| Planejamento | somente SPEC draft |\n| Pronto para Executar | PRD/SPEC ready e Task avulsa nao iniciada |\n| Execucao | Task executing e SPEC/PRD active |\n| Verificacao | Task verifying ou macro nos gates parentais |\n| Finais | completed/delivered, blocked, failed ou cancelled |\n\n## Execution, Runs, Sub-Runs e Calls\n\n- Execution `interaction` registra conversa/definição; `delivery` coordena o trabalho materializado e sua DAG quando aplicável.\n- Run e a chamada raiz do `zaip-agent-orchestrator`; possui `parent_run_id` nulo.\n- Sub-Run e cada chamada de subagente; possui `parent_run_id` e compartilha o mesmo ledger `RUN-*`.\n- Novas gravacoes usam somente `run_role: intake|orchestrator|subagent`; `owner|contributor` sao valores historicos aceitos apenas na leitura e normalizados imediatamente.\n- `run_purpose` distingue `orchestration`, `execution`, `review`, `audit` e `finalization`.\n- cada Run/Sub-Run fixa agente, modelo e effort; mudanca deliberada abre outra chamada de agente.\n- Calls e ferramentas sao eventos internos; quantidade, tokens e custo ficam agregados na Run/Sub-Run, sem tela propria.\n\nToda delivery e interaction com descendentes exigem ao menos um executor\nelegível por capacidade e o `zaip-agent-finalizer` como último filho. Ele aguarda\nos demais descendentes, bloqueia novas chamadas e retorna a decisão restrita\npara a CLI aplicar. Interaction read-only sem descendentes termina após a\nresposta, sem executor/finalizador. Publicação puramente Git não cria lifecycle.\nStatus técnico da chamada de agente e resultado do trabalho são independentes.\n\n`blocked` e retomavel com `task resume`; `failed` exige `task rework` na mesma Task e nova tentativa. `completed` e `cancelled` sao imutaveis. Interromper geracao bloqueia; cancelar a Task explicitamente cancela.\n\n`finalize|conclua` em macro `draft|ready` significa lapidar e deixar pronto; em trabalho ativo, “conclua a execução/finalize a implementação” continua Tasks e gates. `implemente` é sensível ao estado; `desenvolva|melhore|aprimore` sempre planeja/refina/rework. PRD cancelado gera sucessor vinculado com tag `rework`.\n\n## SPEC e PRD\n\nAo iniciar a primeira Task filha, os pais ficam active/Execucao e permanecem assim entre Runs. Task bloqueada ou falhada nao bloqueia automaticamente o pai. Depois que todas as Tasks concluem, SPEC/PRD entram em verificacao parental; apenas gates de integracao, Acceptance Criteria, outcomes e Evidence entregam o macro.\n\nObservações declaradas seguem o contrato de\n[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).\nElas não mudam status da Task nem permitem à reconciliação inferir sucesso.\n\nNovas SPECs de um PRD não possuem dependências entre si: são capacidades paralelizáveis e verificáveis isoladamente. Dependências e ordem ficam nas Tasks da mesma SPEC; integração final é gate parental.\n\n## Reconciliacao\n\nO popup Reconciliar chama `run reconcile --open` somente depois da confirmacao humana. Nao existe varredura ao abrir o dashboard, por turno ou por intervalo.\n\nO reparo e idempotente: `task_complete` local exato permite tentar conclusao; gate insuficiente usa blocked; Run sem invocacao ativa por dez minutos usa failed; cancelled nunca e inferido. Projecoes exibem o status persistido e nao revivem Task terminal por atividade local obsoleta.\n\n## Mutacoes\n\nCodigo, documentacao e configuracao exigem Task materializada e Run raiz ativa antes da escrita. Sao isentos deploy/publicacao Git sem mudanca de produto, manifests e telemetria ZAIP gerados pelo lifecycle, metadados `.git`, caches, builds, testes e temporarios descartaveis. O hook pre-write faz checagem local do turno, sem tokens e sem reconciliacao global.\n",y=`# Como o custo é calculado
+
+Cada estimativa de custo começa em tokens de uma chamada LLM capturados por fonte aceita. O dashboard não estima uso ausente: tokens ou custo sem os componentes necessários permanecem indisponíveis. Uma duração estimada é uma derivação identificada por proveniência e não preenche telemetria de uso.
+
+## 1. Separe os componentes de uso
+
+- **Tokens de input** incluem instruções, histórico, contexto, ferramentas e a mensagem atual.
+- **Tokens de cache** fazem parte do input, não são uma quantidade extra. Eles são subtraídos do input antes da aplicação da sua própria tarifa.
+- **Tokens de output** são tudo que o modelo gerou.
+- **Tokens de reasoning** fazem parte do output. O output é cobrado uma única vez, então reasoning não cria uma segunda cobrança.
+
+## 2. Aplique as tarifas publicadas do modelo
+
+O modelo e o tier de serviço efetivamente observados, quando disponíveis, definem a tabela de tarifas. Para uma chamada, o total em USD é:
+
+| Componente | Cálculo |
+| --- | --- |
+| Input faturável | \`(input - cache) / 1.000.000 × tarifa de input\` |
+| Cache | \`cache / 1.000.000 × tarifa de cache\` |
+| Output | \`output / 1.000.000 × tarifa de output\` |
+
+O dashboard soma esses componentes uma única vez. Quando a identidade do modelo/tier, os tokens necessários ou uma tarifa do catálogo versionado não existem, o custo permanece indisponível em vez de ser inventado.
+
+## 3. Considere contexto, velocidade e esforço
+
+Acima do limite de contexto longo de um modelo, o multiplicador publicado de input também vale para cache e o multiplicador de output vale para todo o output. \`priority\` usa a tabela publicada correspondente quando disponível. \`fast\` do Codex pode ser apresentado apenas como cenário API Priority equivalente; não prova atendimento API em Priority. O multiplicador exibido é uma comparação com Standard, nunca uma cobrança extra.
+
+O esforço não possui multiplicador direto de preço. Ele só pode aumentar o custo indiretamente quando aumenta reasoning, output ou ciclos de execução registrados.
+
+## 4. Converta para a moeda selecionada
+
+O total da chamada é calculado primeiro em USD. Em BRL, a estimativa exige uma cotação identificada; a cotação histórica registrada e a cotação corrente são fontes distintas. Mudar a moeda de exibição nunca altera a telemetria de tokens nem o cálculo em USD.
+`,b='# Catálogo de agentes\n\n`.agents/config/agents/catalog.yaml` é a única fonte canônica dos agentes ZAIP. Adapters Codex e Claude são projeções geradas: depois de qualquer alteração no catálogo, execute `node packages/cli/dist/index.js adapters build` e valide com `node packages/cli/dist/index.js adapters check --json`.\n\n## Identidade técnica e persona\n\nCada agente possui identidade técnica estável: `id` e `codex_name`. A persona editável é `persona.nome` e `persona.cargo`, ambos em snake_case. Ela produz, sem crescimento entre invocações, o `codex_task_name` e exatamente um candidato idêntico:\n\n```text\ncodex_task_name = "{nome}_{cargo}_zaip_agent"\nnickname_candidates = ["{nome}_{cargo}_zaip_agent"]\n```\n\nO schema e a API rejeitam um task name ou nickname manual, múltiplos candidatos ou valores que não sejam a derivação acima. O Dashboard omite esses campos no payload e envia somente a persona; uma edição de persona preserva a identidade técnica. Snapshots de Run usam a identidade de catálogo observada e não inventam persona.\n\n## Agentes canônicos\n\n| person | função | zaip-agent | codex_task_name | descrição resumida da função | quando chamar | quando não chamar | palavras-chave importantes para acionar agent |\n| --- | --- | --- | --- | --- | --- | --- |\n| Dave | Product Owner | `zaip-agent-orchestrator` | `dave_product_owner_zaip_agent` | Organiza a entrega, resolve a DAG e delega com menor privilégio. | Trabalho executável com mais de uma etapa ou especialista. | Implementação direta, revisão ou aprovação. | `orchestration`, `dag`, `delegation`, `lifecycle` |\n| Rafa | Tech Lead | `zaip-agent-builder` | `rafa_tech_lead_zaip_agent` | Cria/refina SPECs e executa delivery genérico, inclusive dashboard/local. | Definição técnica ou mudança sem especialista mais específico. | PRD, design central, website, frontend ou backend especializados. | `spec`, `architecture`, `decomposition`, `dashboard`, `local` |\n| Leo | Software Engineer | `zaip-agent-task-executor` | `leo_software_engineer_zaip_agent` | Executa Task genérica delimitada, inclusive dashboard/local, e produz evidência. | Task pronta, autocontida e sem escopo de especialista obrigatório. | Planejamento macro, coordenação ou revisão independente. | `task`, `implementation`, `verification`, `evidence`, `local` |\n| Bia | Product Manager | `zaip-agent-analyst` | `bia_product_manager_zaip_agent` | Cria/refina PRDs e analisa interações sem antecipar Tasks de delivery. | Problema de produto, PRD, descoberta, escopo ou refinamento. | SPEC, implementação, aprovação técnica ou deploy. | `prd`, `product`, `discovery`, `requirements`, `problem` |\n| Gui | Quality Assurance Lead | `zaip-agent-finalizer` | `gui_quality_assurance_lead_zaip_agent` | Avalia a barreira final e emite somente o resultado terminal permitido. | Obrigatoriamente como último Sub-Run de interação ou delivery. | Antes de executor/revisor terminar ou para corrigir código. | `finalization`, `terminal`, `barrier`, `task-finalizer` |\n| Nanda | Principal Engineer | `zaip-agent-reviewer` | `nanda_principal_engineer_zaip_agent` | Revisa Requirements, diff, testes e evidências sem mutar produto. | Mudança implementada que precisa de revisão independente. | Para implementar a própria correção ou integrar worktrees. | `review`, `findings`, `requirements`, `diff` |\n| Dani | Integration Engineer | `zaip-agent-integrator` | `dani_integration_engineer_zaip_agent` | Integra trabalho revisado e executa gates combinados. | Worktrees ou mudanças independentes já revisadas. | Antes da revisão ou para criar requisitos. | `integration`, `merge`, `combined-gates`, `worktree` |\n| Ana | Quality Auditor | `zaip-agent-auditor` | `ana_quality_auditor_zaip_agent` | Reproduz evidências e emite auditoria independente. | Risco alto, release ou alegação que exige reprodução final. | Implementação, correção ou autoria da evidência. | `audit`, `reproduce`, `release`, `quality` |\n| Lia | Technical Writer | `zaip-agent-writer` | `lia_technical_writer_zaip_agent` | Produz resumo fiel, análise de transcrição com timestamps e documentação grounded em fontes. | Resumo delimitado, transcrição timestampada ou documentação com fontes declaradas. | Pesquisa sem fontes, decisão de produto ou afirmações não suportadas. | `summary`, `transcript`, `timestamps`, `source-grounding`, `documentation` |\n| Gabi | Data Analyst | `zaip-agent-data-analyst` | `gabi_data_analyst_zaip_agent` | Analisa datasets delimitados com método, incerteza e reprodução. | Métricas, dados estruturados ou diagnóstico quantitativo. | Sem dados, para implementar produto ou editar dashboard. | `data`, `metrics`, `analysis`, `dataset` |\n| Tati | Refactoring Specialist | `zaip-agent-refactoring-specialist` | `tati_refactoring_specialist_zaip_agent` | Planeja e executa refactors, migrações e modularização com inventário, mapa, slices reversíveis e gates. | Refactor, migração, arquitetura, modularização ou inventário de código. | Mudança pontual sem refactor, UI central de design ou deploy. | `refactor`, `migration`, `modularization`, `inventory`, `refactor-map`, `rollback` |\n| Doug | Frontend Specialist | `zaip-agent-frontend` | `doug_frontend_specialist_zaip_agent` | Implementa somente `apps/frontend/**`, acessibilidade e integração conforme `DESIGN.md`. | `apps/frontend/**` ou capability explícita de frontend. | Dashboard/local, website institucional, backend ou regra central de design. | `frontend`, `ui`, `accessibility`, `visual-contract` |\n| Will | Backend Specialist | `zaip-agent-backend` | `will_backend_specialist_zaip_agent` | Implementa backend, APIs, persistência e integrações. | `apps/backend/**`, `modules/**` ou capability de backend. | Frontend, website ou design visual central. | `backend`, `api`, `persistence`, `integration` |\n| Jonny | Website Developer | `zaip-agent-website-developer` | `jonny_website_developer_zaip_agent` | Cria sites/LPs com stack do framework, SEO, GEO e acesso por agentes. | `apps/site/**`, site institucional, LP, SEO, GEO ou Markdown for Agents. | App de produto, backend ou mudança da regra central de design. | `website`, `landing-page`, `seo`, `geo`, `markdown-for-agents`, `agent-readiness` |\n| Manu | Product Designer | `zaip-agent-designer` | `manu_product_designer_zaip_agent` | Governa `DESIGN.md`, design tokens (cor, tipografia, espaçamento e raio), componentes centrais e páginas de catálogo digital. | Regra central de design, Design System, tokens, `design-system` ou `componentes`. | Word, PPT, imagem de marketing ou componente local que apenas consome regras existentes. | `design-system`, `design.md`, `tokens`, `central-components`, `componentes` |\n\n| Dan | Cloud Engineer | `zaip-agent-cloud-engineer` | `dan_cloud_engineer_zaip_agent` | Projeta e valida infraestrutura cloud declarada. | Infraestrutura cloud, provisionamento, containers, Terraform ou Docker. | Implementação de aplicação, deploy ou infraestrutura fora do escopo declarado. | `cloud`, `terraform`, `docker`, `provisioning` |\n| Luiz | Security Auditor | `zaip-agent-security-auditor` | `luiz_security_auditor_zaip_agent` | Audita segurança de forma independente e somente leitura. | Auditoria de segurança, mudança sensível ou release que exige avaliação independente. | Implementação, autoria de remediação ou deploy. | `security`, `audit`, `risk`, `release` |\n| Lucia | Marketing Analyst | `zaip-agent-marketing-analyst` | `lucia_marketing_analyst_zaip_agent` | Planeja marketing, copy, campanhas e briefs de imagem com evidência. | Estratégia de marketing, campanha, copy de landing page ou brief de imagem. | Implementação de produto, backend ou governança central de design. | `marketing`, `copy`, `campaign`, `image-brief` |\n| Sarah | Branding Specialist | `zaip-agent-brand-strategist` | `sarah_branding_specialist_zaip_agent` | Define e governa plataforma de marca, Brandbook, posicionamento, arquétipos, diferencial semântico e arquitetura de marca com evidências. | Estratégia ou governança de marca, Brandbook, posicionamento, arquétipos, arquitetura de marca ou consistência de identidade como decisão principal. | Aplicação rotineira de marca aprovada, campanha, script comercial, análise quantitativa bruta ou documento geral sem decisão de marca. | `branding`, `brandbook`, `positioning`, `archetypes`, `semantic-differential`, `brand-architecture` |\n| Robert | Growth Strategist | `zaip-agent-growth-strategist` | `robert_growth_strategist_zaip_agent` | Orienta estratégia de crescimento, RevOps, experimentos, receita, custos e recomendações executivas baseadas em dados. | Estratégia de negócio, Growth, RevOps, modelo de negócio, priorização de portfólio ou impacto financeiro como decisão principal. | Campanha ou conteúdo, Brandbook, playbook comercial, validação quantitativa bruta ou ato comercial externo. | `growth`, `revops`, `experimentation`, `revenue`, `cost-optimization`, `business-strategy` |\n| Aaron | Sales Specialist | `zaip-agent-sales-specialist` | `aaron_sales_specialist_zaip_agent` | Cria processos, playbooks, qualificação, scripts, enablement e handoffs comerciais internos. | Metodologia comercial, qualificação, negociação preparada, processo SDR/closer, script, playbook ou handoff de pipeline. | Estratégia de Growth/RevOps, campanha ou copy de marketing, governança de marca, análise bruta de dados, política jurídica ou ato comercial externo. | `sales`, `qualification`, `sales-playbook`, `sales-script`, `sdr`, `closer`, `pipeline-handoff` |\n| Clara | Operations Generalist | `zaip-agent-general-operations` | `clara_operations_generalist_zaip_agent` | Executa artefatos operacionais delimitados fora de escopos especialistas: documentos, apresentações, planilhas, processos e comparativos. | Documento, apresentação, planilha, processo ou pesquisa comparativa sem capability especialista obrigatória. | Produto, design-system, marketing, dados, segurança, cloud, jurídico vinculante ou ato externo. | `operations`, `document`, `presentation`, `spreadsheet`, `process`, `comparison` |\n| Renata | Governance Compliance Specialist | `zaip-agent-governance-compliance` | `renata_governance_compliance_specialist_zaip_agent` | Prepara artefatos internos não vinculantes de RH, jurídico operacional, política, privacidade, fornecedores e risco. | Minuta, checklist, matriz de risco ou pacote interno de aprovação sem ato externo. | Parecer jurídico vinculante, assinatura, representação, protocolo, contratação ou decisão humana. | `governance`, `compliance`, `hr`, `legal-operations`, `privacy`, `vendor`, `risk` |\n\n## Squads organizacionais\n\nO catálogo contém 23 agentes agrupados visualmente em seis squads: **Product** (3), **Admin & Operations** (3), **Development** (6), **Delivery Assurance** (4), **Infra & Security** (2) e **Growth — Sales, Marketing and Branding** (5). A soma é 23.\n\nOs squads facilitam a leitura organizacional e a colaboração humana. Eles não são uma fonte de roteamento: `selectAgentForWork` continua a escolher o agente exclusivamente pelas capabilities mandatórias, escopos explícitos, prioridade e ID; cada agente conserva seus write scopes e permissões.\n\n## Roteamento determinístico\n\n`selectAgentForWork` deriva uma capacidade mandatória a partir de escopos explícitos antes de aplicar a seleção ordenada por prioridade e ID.\n\n- `.agents/design/*`, `.agents/design/**`, `DESIGN.md`, `tokens.json`, `apps/catalog/**` ou capability explícita de Design System/tokens/componentes/páginas seleciona Manu. Manu é a regra visual central; Doug somente a consome em `apps/frontend/**`.\n- `apps/site/**` ou capability explícita `website-delivery`, SEO, GEO, Markdown for Agents ou Agent Readiness seleciona Jonny.\n- `apps/frontend/**` seleciona Doug quando a capability é frontend; `apps/backend/**` e `modules/**` selecionam Will quando a capability é backend.\n- Capabilities de governança, RH, jurídico operacional, políticas, privacidade, fornecedores ou riscos selecionam Renata. Ela prepara o pacote revisável e a ação humana necessária, mas não executa ato vinculante ou externo.\n- Capabilities de plataforma ou governança de marca, Brandbook, posicionamento, arquitetura de marca, arquétipos ou diferencial semântico selecionam Sarah. Ela governa a identidade e encaminha aplicação de design system para Manu e ativação de marketing para Lucia.\n- Capabilities de estratégia de Growth, RevOps, experimentação, receita, custo, funil, unit economics ou recomendação executiva selecionam Robert. Dados quantitativos delimitados continuam com Gabi, e processos comerciais internos com Aaron.\n- Capabilities de metodologia comercial, qualificação, playbooks, scripts, SDR, closer ou handoff de pipeline selecionam Aaron. Ele não realiza ato comercial externo nem substitui Sarah, Lucia, Robert ou Gabi em suas fronteiras especializadas.\n- Capabilities de documentos, apresentações, planilhas, processos e comparativos — ou trabalho delimitado sem capability explícita e sem escopo obrigatório — selecionam Clara como fallback operacional contínuo.\n- Um diretório chamado `components` fora dos alvos canônicos não aciona Manu. O orquestrador usa a capability solicitada e os write scopes da Task.\n- `.agents/dashboard/**` e `.local/**` não selecionam Doug nem Manu: permanecem com Rafa ou Leo até que a Task declare um escopo obrigatório; artefatos operacionais não técnicos podem selecionar Clara.\n\nO orquestrador mantém a Run raiz e cada Run delegada separadas na observabilidade. Duração, tokens e custo só são agregados quando observados ou reconciliados; ausência continua indisponível, nunca zero.\n\nO dispatch autônomo passa os `Task.write_scopes` a essa seleção **por Task** e persiste o builder escolhido na entrada de cada Task. Assim uma DAG com frontend e backend usa Doug e Will nas respectivas invocações, sem transformar a seleção de uma Task em builder global. A seleção é determinística, mas não concede autoridade: o agente ainda precisa respeitar seus write scopes e permissões do catálogo.\n\nO `budget.soft_cycles` também acompanha o agente selecionado por Task e governa seu checkpoint suave. Tokens continuam observados para telemetria e custo, mas não interrompem nem exigem checkpoint. Para comparar agentes, use `zaip run aggregate --agent agent-ID`; o resultado inclui duração coberta, ciclos de uso observados, tokens, custo, cobertura e Runs de rework.\n\nNanda (`agent-reviewer`) usa `gpt-5.6-terra` com esforço `medium` e `soft_cycles: 12`, proporcional à revisão standard. Ana (`agent-auditor`) permanece `gpt-5.6-sol`/`high` para auditoria crítica ou explicitamente auditável; Luiz (`agent-security-auditor`) permanece `gpt-5.6-sol`/`high` para auditoria de segurança explícita.\n\n## Dashboard e segurança operacional\n\nA tela **Configurações > Catálogo de agentes** apresenta a persona e mantém a identidade técnica somente leitura. Ao salvar, o runtime valida o catálogo, deriva o único nickname, sincroniza adapters e reverte a escrita se a paridade falhar. Agentes de framework permitem alteração de persona e preferências de modelo/effort; propósito, capacidades e identidade técnica continuam protegidos.\n',x=`# Assurance adaptativa e autonomia opt-in
+
+O ZAIP-AIOS separa duas decisões que não devem ser confundidas: quanto de prova uma entrega exige e quem executa a DAG. A primeira é governada por \`assurance\`; a segunda por \`execution\`. O modo manual continua sendo o padrão seguro e econômico.
+
+## Matriz de validação
+
+| Origem e risco | Validações aprovadas | Evidences aprovadas | Controles adicionais |
+| --- | ---: | ---: | --- |
+| Task standalone \`lite\` | 1 ou mais; normalmente 1 | 1 ou mais; normalmente 1 | cobertura completa dos ACs; provas extras legítimas são aceitas |
+| Task standalone \`standard\`, base | 2 ou mais | 1 ou mais, com pelo menos 1 Evidence consolidada | modalidades distintas; inclui teste |
+| Task standalone \`standard\`, elevado | 3 ou mais | 1 ou mais, com pelo menos 1 Evidence consolidada | modalidades distintas; inclui teste |
+| Task standalone \`critical\` | 3 ou mais | 1 dedicada por AC quando o sinal persistido exigir | teste, quality review independente e controles dirigidos pelos sinais |
+| Entrega de SPEC | 3 ou mais parentais | 3 ou mais parentais | matriz de AC, integração, spec review, quality review e commit final |
+| Entrega de PRD | 3 ou mais parentais | 3 ou mais parentais | matriz de AC/outcome, cross-SPEC E2E, spec review, quality review e commit final |
+
+Uma única Evidence pode cobrir vários ACs nos perfis \`lite\` e \`standard\`, e nos perfis parentais que não exigem Evidence dedicada por AC. Em todos os casos, a cobertura precisa ser completa e a Evidence deve referenciar uma validação tipada aprovada da mesma Task, Change e Execution. Texto declarando que algo passou não é prova.
+
+## Observação por AC
+
+Para entrega nova ou verificação retomada, use o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
+Uma observação descreve o cenário, expectativa, resultado, ambiente,
+candidato, locators e limitações. O CLI valida estrutura e vínculos, mas não
+executa o comando declarado, não examina pixels e não consulta banco
+automaticamente. Só observação \`confirmed\` e compatível pode complementar uma
+Evidence; nunca a aprova isoladamente. Históricos V2 sem observações continuam
+legíveis e não são promovidos retroativamente.
+
+Conteúdo de novos registros passa também por rejeição de padrões conhecidos
+de credenciais, sem ecoar valores no erro. Isso não valida a autenticidade
+da observação nem substitui sanitização e revisão humana dos locators.
+
+\`standard_depth: auto\` escolhe o perfil base quando \`verification_scope: scoped\` está persistido e o elevado para escopo mais amplo. Para registros históricos sem esse sinal, o fallback conservador usa mais de um write scope; ele não substitui a classificação nova. O perfil \`lite\` não é permitido como atalho para segurança, migração, irreversibilidade ou mudança multi-domínio crítica.
+
+Em \`critical\`, a revisão de qualidade independente é sempre exigida. Mutação é exigida apenas para segurança ou dados críticos; rollback para migração, irreversibilidade ou rollback não trivial; e Evidence por AC para segurança ou migração. Evidência de commit final é exigida para impacto em produção, ação externa ou migração. Esses controles são decididos pelos sinais de risco persistidos, não por quotas máximas de artefatos.
+
+## Ativação segura
+
+Configuração recomendada para uso normal:
+
+\`\`\`yaml
+execution:
+  runtime: manual
+assurance:
+  version: 1
+  standard_depth: auto
+  require_final_commit: true
+\`\`\`
+
+\`require_final_commit: true\` impede que validações antigas ou feitas antes da integração comprovem o candidato atual. Durante uma migração controlada do próprio framework, ele pode ser temporariamente \`false\`, mas a exceção precisa ser explícita e não qualifica cleanroom ou release.
+
+## Runtime autônomo
+
+Autonomia exige configuração explícita:
+
+\`\`\`yaml
+execution:
+  runtime: autonomous
+  autonomous:
+    provider: codex
+    model: MODELO-PERMITIDO
+    max_parallelism: 3
+    lease_ms: 900000
+\`\`\`
+
+O projeto ZAIP-AIOS limita a concorrência produtiva a \`max_parallelism: 3\`, mas inicia em 1. A elevação só ocorre quando existem ramos sem dependência e sem sobreposição de write scope; o coordenador reivindica cada lote novamente com os locks do scheduler. O paralelismo efetivo é sempre o menor limite entre projeto, plano independente, provider e squad. \`budget.soft_cycles\` é aplicado ao agente escolhido em cada Task; tokens permanecem telemetria e custo, não checkpoint. \`zaip run aggregate --agent agent-ID\` filtra a identidade e retorna duração, ciclos observados, tokens, custo, cobertura e rework. Telemetria não capturada permanece indisponível, nunca zero.
+
+O runtime cria Executions-filhas determinísticas somente para SPECs com dependências internas e write scopes globalmente disjuntos. Cada filha possui coordinator, estado, quota de orçamento e handoff próprios, mas todas compartilham a fila limitada pelo paralelismo efetivo e o ledger de invocações do PRD. A filha termina antes do fan-in e o pai não reexecuta suas Tasks. A Execution do PRD integra os commits das filhas, executa as modalidades parentais sobre o commit combinado e bloqueia o finalizer enquanto houver filha ativa. SPECs inelegíveis continuam na DAG global, preservando locks, orçamento e segurança do coordenador.
+
+O driver autônomo:
+
+- usa protocolo nativo JSONL de Codex ou Claude, sem shell;
+- cria worktree Git por Task a partir de uma raiz limpa;
+- limita alterações aos write scopes;
+- exige commit final e valida os artefatos tipados dentro da worktree;
+- aborta merge conflitante e não deixa merge parcial;
+- persiste estado com compare-and-swap;
+- serializa somente transições do estado durável e rebaseia cada Task, permitindo que invocações de ramos independentes executem em paralelo com segurança;
+- mantém checkpoints opacos somente em \`.local\`;
+- limita \`lite\` a uma tentativa e \`standard\`/\`critical\` a no máximo três tentativas de desenvolvimento ou reparo;
+- usa verificador independente para critical, SPEC e PRD.
+
+Na Task autônoma, o adapter respeita o mesmo rigor calculado: \`lite\` não exige
+um teste quando a política permite outra modalidade; mutação e rollback
+exigidos precisam de provas tipadas, inclusive em Task crítica sem pai.
+Sinais de risco ausentes mantêm o fallback conservador. Artefatos históricos
+de outra Run ou candidato não aprovam a entrega atual nem impedem uma nova
+aprovação quando as provas atuais estão completas. Limites de invocação são
+reservados atomicamente e retomadas não zeram o consumo acumulado.
+
+Ativar \`autonomous\` não afirma que o runtime está validado em produção. A maturidade só avança quando o mesmo hash do candidato passa validação local, cleanroom, ambiente representativo e observação de produção, nessa ordem.
+
+## Cobertura e release
+
+O ratchet de cobertura nunca reduz o piso: 80% para lines, functions e statements e 75% para branches. Uma medição atual abaixo disso pode ser registrada como baseline observada para diagnóstico, mas o gate continua vermelho. Release crítica também exige unit, E2E, arquitetura, CQRS, módulos, profile, segurança, testes negativos, paridade da distribuição e cleanroom do candidato exato.
+`,S='# Como instalar e rodar o ZAIP-AIOS\n\nEste 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`.\n\n## Pré-requisitos\n\n- 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;\n- Git;\n- permissões de escrita no repositório consumidor.\n\nO consumidor não precisa compilar o monorepo nem instalar pnpm para executar\no runtime distribuído. No checkout mantenedor, use o pnpm fixado em\n`packageManager` (11.12.0 neste snapshot), com `corepack pnpm` quando disponível.\n\n## Instalação pública no projeto consumidor\n\nNa raiz do projeto-alvo:\n\n```bash\nnpx @zaip-ai/cli@latest init --dry-run\nnpx @zaip-ai/cli@latest init\nnode .agents/runtime/bin/zaip.mjs doctor --json\n```\n\nRevise o dry-run antes da instalação. `@latest` seleciona a versão publicada,\nnão alterações ainda locais neste repositório. O binário público `zaip` é o\ninstalador; nos exemplos de lifecycle deste guia, `zaip ...` é uma abreviação\nde `node .agents/runtime/bin/zaip.mjs ...` no projeto consumidor. Use o caminho\nexplícito para evitar colisão entre os dois CLIs.\n\n## Construir o CLI\n\nSomente no repositório-fonte, para manutenção do framework:\n\n```bash\ncorepack pnpm install --frozen-lockfile\ncorepack pnpm build\nnode packages/cli/dist/index.js version\n```\n\nNesse checkout compilado, use `node packages/cli/dist/index.js ...` para os\ncomandos de lifecycle. Em `--workspace`, informe o destino autorizado; não\nconfunda a raiz fonte com o projeto consumidor.\n\n## Setup pelo CLI de lifecycle\n\nFaça primeiro um dry-run e revise conflitos:\n\n```bash\nzaip setup --workspace /caminho/do/projeto --dry-run --json\nzaip setup --workspace /caminho/do/projeto\nzaip doctor --workspace /caminho/do/projeto\n```\n\nO setup V2 cria ou valida:\n\n```text\n.agents/config/{project.yaml,framework.lock.yaml}\n.agents/rules/{core,workflow,architecture,security,context}.md\n.agents/requirements/{work-lifecycle,execution-engine,cost-observability,kanban-dashboard,context-engine,software-architecture}.md\n.agents/skills/\n.agents/records/{prds,specs,changes,tasks,executions,runs}/\n.agents/records/lifecycle/\n.local/claims/                 # claims idempotentes do lifecycle; não é histórico canônico\n```\n\nO runtime `.agents/runtime` usa a `.agents/` da raiz como fonte canônica das Rules, dos seis\nRequirements de área e das skills. Em uma instalação nova, o setup cria config e os seis diretórios\nvazios de data, projeta somente os arquivos portáveis do framework e registra a versão de origem em\n`source_release`. Histórico, Changes, Tasks, Runs e aliases específicos deste repositório nunca são\ncopiados para o projeto consumidor.\n\nO setup identifica a propriedade pelo `framework.lock.yaml`: Rules presentes no lock pertencem ao\nframework; as demais são locais ao projeto e são preservadas em instalações e upgrades. Conflitos\nde ID ou contradições bloqueiam a operação; não existe override silencioso.\n\nTambém gera adapters mínimos, como `AGENTS.md` e `CLAUDE.md`, sem sobrescrever conteúdo do usuário silenciosamente.\n\n## Migrar estado V1\n\n```bash\nzaip migrate plan --workspace /caminho/do/projeto --json\nzaip migrate plan --workspace /caminho/do/projeto --verbose --json\nzaip migrate apply --workspace /caminho/do/projeto --plan-hash HASH\nzaip migrate status --workspace /caminho/do/projeto\n```\n\nPor 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`.\n\nA migração deve ser idempotente. Até ser aplicada e verificada, raízes V1 permanecem legado somente leitura. Para desfazer uma migração suportada:\n\n```bash\nzaip migrate rollback --workspace /caminho/do/projeto --migration ID\n```\n\n## Escolher a entrada certa\n\nUse 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.\n\nPRD e SPEC são opcionais. O intake captura uma vez por turno observável;\ncontinuação reutiliza o foco válido e publicação puramente Git não cria\nlifecycle. Para pergunta, feedback ou análise read-only, `conversation start`\ne `conversation finish` registram uma interaction sem Task/Change artificial.\nCriar/refinar explicitamente PRD/SPEC `draft` pode persistir macro e PreparedPlan\nna própria interaction, sem delivery. Fora dessa exceção, alterações persistentes\nde código, documentação ou configuração exigem delivery, Task materializada e\nRun raiz ativa antes da escrita; caches/builds e projeções geradas seguem as\nisenções da Rule de workflow. Interaction read-only sem descendentes não exige\nexecutor nem finalizador.\n\nUma 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).\n\n## Task-first\n\nCrie o draft manual, prepare e execute explicitamente:\n\n```bash\nzaip task create --title "Ajuste pontual" --short-name ajuste-pontual --objective "Resultado esperado" --requirements REQ-ID --acceptance AC-ID --write-scopes src/**\nzaip task prepare TASK-ID\nzaip task execute TASK-ID\n```\n\nTask-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`.\n\nTask-first registra objetivo, Requirements e Acceptance Criteria sem ocupar artificialmente as\ncolunas Definição ou Planejamento. Uma Task criada ou preparada, mas não iniciada, aparece em Pronto\npara executar. Em pedidos diretos de ação, Change, Execution, Task e Run raiz são materializados\nantes da primeira mutação. Verificação e evidências sempre refletem registros reais.\n\nPara uma Task manual com dependências, modele a DAG completa em um draft de plano e gere o contrato canônico antes do prepare:\n\n```bash\nzaip plan build --draft ./task-plan-draft.json --output ./task-plan.json\nzaip plan validate --plan ./task-plan.json\nzaip task prepare TASK-ID --plan ./task-plan.json\nzaip task execute TASK-ID\n```\n\nO draft fornecido a `plan build` contém origem, Changes, Tasks, Execution, Requirements/AC e locks,\nmas não precisa calcular hash ou ordem topológica. Toda Task referenciada por `depends_on` precisa\nestar no mesmo plano. `plan validate` verifica o PreparedPlan completo sem materializá-lo.\n\n## SPEC opcional\n\n```bash\nzaip spec create --title "Objetivo técnico" --short-name objetivo-tecnico --objective "Resultado esperado"\nzaip spec prepare SPEC-ID --plan ./spec-plan.json\nzaip spec show SPEC-ID\nzaip spec execute SPEC-ID\n```\n\n`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.\n\n## PRD opcional\n\n```bash\nzaip prd create --title "Resultado de negócio" --short-name resultado-negocio --problem "Problema a resolver"\nzaip spec create --prd PRD-ID --title "Entrega técnica" --short-name entrega-tecnica --objective "Resultado técnico"\nzaip prd prepare PRD-ID --plan ./prd-plan.json\nzaip prd show PRD-ID\nzaip prd execute PRD-ID\n```\n\nÉ 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.\n\nNa 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.\n\n`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.\n\n## Refinar sem executar\n\nNão existe comando `refine`. Enquanto PRD, SPEC ou Task estiver em `draft`, edite seu Markdown\ncanônico em `.agents/records`, incremente `revision` e atualize `updated_at`; em seguida use `show` e\nos validadores aplicáveis. Depois de `prepare`, não altere o plano silenciosamente: volte a um\ndraft por uma transição explicitamente suportada pela política da entidade ou cancele e crie um\nnovo draft. Isso preserva hash, auditoria e leitura humana.\n\nPara 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.\n\n## Executar e acompanhar a DAG\n\n```bash\nzaip execution list\nzaip execution show EXEC-ID\nzaip execution start EXEC-ID\nzaip task next\nzaip task start TASK-ID\nzaip 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\n# execute e verifique o trabalho\nzaip 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\nzaip run finish RUN-FINALIZADOR-ID --status completed\nzaip run finish RUN-ID --status completed --task-outcome completed --summary "Resultado" --evidence EVD-ID --changed-files src/arquivo.ts\nzaip run closure RUN-ID\n```\n\nTasks `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.\n\nCada 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.\n\n### Assurance e autonomia\n\nAtive a garantia tipada sem ativar execução por provider:\n\n```yaml\nexecution:\n  runtime: manual\nassurance:\n  version: 1\n  standard_depth: auto\n  require_final_commit: true\n```\n\nTask 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).\n\n## Changes, decisões e evidências\n\nCada alteração possui `.agents/records/changes/YYYY/MM/CHG-.../change.md`, criado antes da primeira mutação. Ele registra:\n\n- plano e Requirement deltas;\n- implementação;\n- decisões humanas e da IA;\n- evidências por Acceptance Criterion;\n- evals e testes;\n- resultado final.\n\nCada teste, revisão, eval ou check executado também deve gerar um artefato reproduzível em\n`artifacts/tests/`, `artifacts/evals/` ou `artifacts/checks/`. O registro inclui ao menos\n`executed_at` com timezone, comando, status, Task, Run e Acceptance Criteria cobertos. Quando uma\nverificação não se aplica, registre `status: not_applicable` e a justificativa; ausência de registro\npermanece pendência. O dashboard contabiliza testes e considera uma etapa rastreada somente quando\nexiste timestamp de origem, sem substituir ausência pelo horário da consulta.\n\nQuando houver prova observável por AC, siga o contrato\n[canônico](../../skills/zaip-skill-change/references/observable-evidence.md).\n`validation observe` registra uma declaração sanitizada inline; não abre arquivo\nde entrada, não executa o procedimento e não cria Validation aprovada. Somente\numa observação `confirmed` e vinculada pode complementar Evidence já compatível.\n\nDecisõ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.\n\n## Runs e custos\n\nUma 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.\n\nOperaçã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.\n\nA captura do Codex persiste primeiro um envelope sanitizado em\n`.local/codex-telemetry-spool/v1/`, que permanece fora do Git. Depois do terminal da\ninvocação, a compactação produz um `InvocationSummary` e publica chunks e manifestos por\nano/mês/writer em `.agents/records/telemetry/`. Prompts, respostas, reasoning privado e segredos não\nentram nesses arquivos.\n\nQuando o Monitor de Custos recebe `from` e `to`, ele valida hashes e consulta os manifestos antes de\ncarregar somente os chunks compatíveis com o período e os filtros. Na ausência de summaries\naplicáveis, usa a projeção de Run existente sem promover a cobertura. O contrato completo, a\nsemântica de `complete|partial|unavailable` e o procedimento de recuperação estão em\n[Telemetria Git-native do Codex](27-telemetria-git-native.md).\n\nO 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.\n\n```bash\nzaip 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\nzaip run usage RUN-ID --input-tokens N --output-tokens N\nzaip run finish RUN-ID --status completed --task-outcome completed --summary "Resultado" --evidence EVD-ID --changed-files src/arquivo.ts\nzaip run closure RUN-ID\nzaip run show RUN-ID\nzaip run list --phase execution --task TASK-ID --limit 50\nzaip run aggregate --prd PRD-ID --from 2026-07-01 --to 2026-07-31\n```\n\n`run-v2` permanece alias compatível. `run list` retorna resumos compactos e paginados; combine\n`--phase`, `--entrypoint`, `--work-type`, `--conversation`, `--execution`, `--change`, `--task`,\n`--spec`, `--prd`, período e paginação. `run aggregate` usa os mesmos filtros para totalizar uso,\ncusto e cobertura sem dupla contagem. Valores ausentes permanecem nulos; dashboards mostram\ncobertura para impedir que custo desconhecido pareça custo zero.\n\nReconciliação global não roda ao abrir o dashboard, a cada turno ou em intervalo. Ela só é executada\nquando uma pessoa confirma o popup **Reconciliar** ou chama explicitamente\n`zaip run reconcile --open`. O reconciliador usa fatos locais: pode concluir uma Task com evento\nterminal exato; marca Run órfão depois da tolerância como falha técnica; transforma ausência de gates\nem bloqueio; e nunca infere cancelamento ou sucesso sem evidência.\n\n## Organizar frontend, backend e site\n\nCrie somente as superfícies usadas pelo projeto, mas preserve seus papéis:\n\n```text\napps/frontend/       # UI do produto\napps/backend/        # APIs e workers\napps/site/           # landing page e site público independente\nmodules/<area>/      # capacidades de negócio\npackages/<library>/  # bibliotecas técnicas\ntests/e2e/           # jornadas entre aplicações\n```\n\nA dependência aponta de `apps` para `modules` e destes para `packages`. O site público não importa\no dashboard, não lê `.agents` e não acessa implementação privada do backend.\n\nO dashboard ZAIP é outra fronteira, em `.agents/dashboard`. Ele possui somente\n`apps/frontend`; o servidor loopback fica em `packages/local-runtime`, acompanhado dos módulos\n`operations`, `cost-monitor` e `traceability`, demais packages próprios e `tests/e2e`. Ele lê\nos manifests canônicos em `.agents/records/lifecycle` e abre os demais records apenas por ID. A única\nreparação global iniciada pela UI ocorre após confirmação explícita no popup Reconciliar e usa o\ncomando canônico de reconciliação; não deve ser movido para o `apps/frontend` do produto\nnem publicado como `apps/site`.\n\nNo repositório-fonte do ZAIP, o gate de tamanho é executado isoladamente com:\n\n```bash\nnode scripts/validate-source-size.mjs\n```\n\nArquivos com 401–800 linhas geram warning; arquivos com 801 ou mais geram erro. Código gerado,\n`dist`, vendor, `node_modules`, `.agents/records` e lockfiles são ignorados. Exceções temporárias\nexistem apenas para legado não-dashboard, não podem crescer e precisam declarar responsável,\nmotivo e expiração.\n\n## Contrato CLI e taxonomia publicados\n\nO lifecycle observável avança em uma única direção: `conversation → planning → execution`. Task,\nSPEC e PRD são entrypoints distintos; Change narra a mutação, Execution coordena a DAG e Run mede\numa tentativa. O manifesto público do CLI cobre estas áreas e ações:\n\n```text\nzaip setup; zaip doctor\nzaip adapters build|check\nzaip context inventory|build|inspect\nzaip manifest rebuild|refresh|show|reconcile\nzaip verify --changed --risk lite|standard|critical\nzaip architecture validate; zaip cqrs validate; zaip modules validate; zaip profile validate\nzaip eval run\nzaip migrate plan|apply|status|rollback\nzaip plan build|validate|normalize\nzaip prd create|list|show|prepare|ready|execute|activate|deliver|block|fail|cancel\nzaip spec create|list|show|prepare|ready|execute|activate|deliver|block|fail|cancel\nzaip change list|show|start|resume|block|verify|complete|fail|cancel\nzaip task create|list|next|show|prepare|execute|start|resume|rework|block|verify|complete|fail|cancel\nzaip execution list|show|start|resume|pause|block|verify|complete|fail|cancel\nzaip conversation start|finish\nzaip subagent capture\nzaip run start|list|aggregate|usage|finish|closure|reconcile|show\nzaip decision list|show|record\nzaip generate; zaip guard diff; zaip ui; zaip version\n```\n\n`pnpm test:contract` impede drift entre este guia, o manifesto de comandos, versões de packages,\nruntime distribuído e o gate de tamanho. `pnpm test:e2e` executa primeiro esse contrato e depois o\nE2E do dashboard.\n\n## Validação\n\n```bash\nzaip adapters check\nzaip context inventory\nzaip architecture validate\nzaip modules validate\nzaip profile validate\nzaip cqrs validate\nzaip eval run\n```\n\n`modules validate` verifica fronteiras entre `apps`, `modules` e `packages`. `profile validate`\nverifica 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\ncommands/queries.\n\nNo repositório-fonte, rode também `pnpm validate:skills` e `pnpm test:encoding` após alterar Rules, Requirements, skills ou documentação.\n',C=`# 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.
+`,w=`# 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).
+`,T=`# Guia de orquestração de modelos e reasoning effort
+
+## Objetivo
+
+Este guia define como o ZAIP-AIOS recomenda modelo, \`reasoning effort\` e velocidade para cada trabalho. A política deve equilibrar quatro resultados:
+
+- alta assertividade na entrega;
+- baixo percentual de bugs e rework;
+- validação proporcional ao risco;
+- economia de tokens, custo e tempo total até a entrega verificada.
+
+Na implementação atual, a política suporta \`manual\`, \`off\` e \`auto\`. No projeto ZAIP-AIOS, \`auto\` está ativado somente para Executions originadas por SPEC ou PRD; Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex. \`manual\` continua disponível para rollback e permanece o default de novas instalações.
+
+Toda Execution originada por PRD ou SPEC solicita velocidade \`standard\`, sem exceção ou override para Fast. A única forma suportada de executar trabalho de produto mais rápido é iniciar uma Task-first realmente independente e selecionar Fast manualmente no Codex; o ZAIP não ativa, persiste nem herda essa velocidade.
+
+## Estado atual
+
+### Estado verificado do framework
+
+O schema canônico de \`project.yaml\` aceita \`manual\`, \`off\` e \`auto\`. O Agent Run registra agente, papel, pai, modelo e \`reasoning_effort\` planejados. O resolvedor aplica política e overrides quando a Run começa; Calls internas apenas herdam essa configuração e acumulam telemetria na própria Run.
+
+Uma mudança deliberada de modelo, effort, agente ou fase material exige uma nova Agent Run. Por isso, uma Task pode usar configurações diferentes em implementação, revisão e rework, desde que cada etapa possua sua própria Run relacionada. Retry técnico e retomada por checkpoint preservam a configuração original.
+
+### Modo manual
+
+Quando \`model_orchestration.mode\` estiver como \`manual\`, o ZAIP:
+
+1. usa modelo, esforço e velocidade somente quando estiverem explícitos no input ou contexto técnico do turno;
+2. classifica o trabalho;
+3. recomenda uma configuração;
+4. informa a recomendação antes de continuar;
+5. nunca altera a configuração automaticamente.
+
+O modo manual não usa hook nem tenta coletar a configuração efetiva no transcript. \`default_model\`, \`default_effort\` e \`default_velocity\` podem orientar uma recomendação, mas não comprovam o que o host executou. Quando modelo, effort ou velocidade efetivos não vierem de fonte observada, registre-os como indisponíveis/\`unknown\`; nunca os infira pelo comportamento aparente do modelo nem os substitua pelo default.
+
+Formato recomendado:
+
+\`\`\`text
+Você está usando o modelo <modelo>, esforço <esforço> e velocidade <velocidade>.
+Esta tarefa é <lite|padrão|crítico>; recomendo esforço <esforço> e velocidade
+<velocidade> porque <motivos observáveis>. Caso concorde, cancele esta tarefa
+e faça a configuração manual no Codex.
+\`\`\`
+
+### Modo automático por origem
+
+O modo automático resolve uma configuração antes de cada Agent Run elegível e preserva separadamente os valores planejados e os valores efetivamente observados. A decisão é metadado estruturado do runtime; instruções em linguagem natural como “use high effort” não garantem mudança real.
+
+O campo \`automatic_sources\` é a fronteira de aplicação. O contrato aceita exatamente \`spec\` e \`prd\`: somente as Tasks materializadas dentro dessas Executions recebem seleção automática, sempre com velocidade \`standard\`. Uma Execution originada diretamente de \`task\`, uma Conversation ou uma Task avulsa não recebe a política e não herda \`default_model\`, \`default_effort\` nem \`default_velocity\`; preserva os três valores escolhidos manualmente no Codex.
+
+Cada Task ou fase materialmente distinta deve executar em seu próprio Agent Run. Calls produzidas durante a Run usam o mesmo modelo e effort. Tasks paralelas podem usar configurações diferentes simultaneamente quando estiverem isoladas em Runs próprias.
+
+O modo automático é híbrido e governado: o modelo pode propor a configuração a partir dos metadados da Task elegível, mas um resolvedor determinístico limita a decisão à allowlist, aos caps e à precedência do projeto. Isso preserva a flexibilidade documentada pelo Codex sem transformar uma decisão de custo e qualidade em texto não auditável.
+
+### Escolha manual no Codex
+
+Um \`.codex/config.toml\` sem cabeçalho \`zaip-managed\` é tratado como overlay local do usuário. \`adapters build\` o preserva e \`adapters check\` o aceita sem mascarar drift nos hooks, regras, instruções e demais projeções gerenciadas. Isso impede que uma atualização do framework restaure silenciosamente um pin de modelo ou apague preferências locais.
+
+Os registros e perfis \`zaip-agent-*\` pertencem exclusivamente ao catálogo do projeto em \`.agents/config/agents/catalog.yaml\`. Para Codex, os perfis gerados ficam em \`.agents/config/clients/codex/agents/*.toml\`, e \`.codex/config.toml\` mantém apenas os registros que os referenciam e o bootstrap nativo. A inicialização não copia configuração de projeto para \`~/.codex\`; somente remove registros globais legados que reutilizem essas identidades técnicas e poderiam prevalecer ou conflitar com o projeto confiável.
+
+O Codex trata \`model\` e \`model_reasoning_effort\` em \`config.toml\` como defaults duráveis. A precedência relevante é: flags/overrides da CLI, \`.codex/config.toml\` do projeto confiável e \`~/.codex/config.toml\`. Portanto, o pin que bloqueia a preferência pessoal é o do projeto, porque ele prevalece sobre o global.
+
+Para permitir escolha manual em Conversation e Task-first, não fixe \`model\`, \`model_reasoning_effort\` nem \`service_tier\` no \`.codex/config.toml\` do projeto. O arquivo global pode guardar a última preferência escolhida manualmente pelo usuário; remova esses campos globais somente quando quiser voltar aos valores recomendados. Reinicie o Codex depois de uma edição externa e use \`/debug-config\` ou \`codex --strict-config\` quando houver dúvida sobre precedência.
+
+## Princípios de decisão
+
+1. **Qualidade é uma restrição, não uma média com custo.** Acceptance Criteria, testes e gates precisam passar antes de otimizar tokens.
+2. **Use o menor effort que entrega a qualidade necessária.** Aumente somente por necessidade observável ou ganho medido.
+3. **Modelo, effort e risco são dimensões diferentes.** O modelo segue a forma e a complexidade da Task; o agente fornece o effort-base; o risco define gates.
+4. **Validação reduz bugs melhor que effort isolado.** Testes determinísticos, revisão independente e auditoria não podem ser substituídos por mais reasoning.
+5. **Custo relevante é o total até a entrega verificada.** Planejamento barato que gera muitos reparos pode custar mais que um planejamento mais profundo.
+6. **Escalada exige evidência.** Ambiguidade, falha estrutural, finding ou rework justificam elevar um nível; volume mecânico não.
+7. **Toda decisão deve ser observável.** Registre a configuração planejada no Agent Run e, quando disponível, a configuração efetiva agregada de suas Calls.
+
+## Família de modelos
+
+A política automática deve permanecer inicialmente na família GPT-5.6:
+
+| Modelo | Uso preferencial |
+| --- | --- |
+| \`gpt-5.6-luna\` | trabalho claro, repetitivo, determinístico e de alto volume |
+| \`gpt-5.6-terra\` | implementação, teste, diagnóstico e integração cotidiana |
+| \`gpt-5.6-sol\` | trabalho ambíguo, transversal, arquitetural, crítico ou de alto valor |
+
+Os defaults iniciais ficam definidos assim:
+
+| Campo | Default |
+| --- | --- |
+| modelo fallback/baseline | \`gpt-5.6-terra\` |
+| effort fallback/baseline | \`medium\` |
+| velocidade fallback/baseline | \`standard\` |
+| modelo eficiente elegível | \`gpt-5.6-luna\` |
+| modelo frontier elegível | \`gpt-5.6-sol\` |
+| teto automático de effort | \`xhigh\` |
+| \`xhigh\` automático | habilitado somente pelos critérios de elegibilidade |
+| \`max\` e \`Ultra\` automáticos | fora de escopo |
+| velocidade solicitada | sempre \`standard\`; não participa da seleção |
+
+Terra \`medium\` é o fallback quando os sinais forem insuficientes ou conflitantes. Sol não deve ser usado em tudo; Luna não deve ser usado quando a Task depende de julgamento arquitetural ou ambiguidade relevante.
+
+\`ultra\` e \`max\` não fazem parte da política: o ZAIP-AIOS nunca os seleciona. A seleção usa somente Luna, Terra ou Sol com effort \`low\`, \`medium\`, \`high\` ou \`xhigh\`.
+
+## Reasoning effort
+
+| Effort | Uso recomendado |
+| --- | --- |
+| \`low\` | execução clara, roteamento, busca delimitada, transformação e integração sem conflito |
+| \`medium\` | padrão para agentic coding, planejamento delimitado, implementação e revisão cotidiana |
+| \`high\` | debugging complexo, planejamento profundo, síntese final e auditoria crítica delimitada |
+| \`xhigh\` | exceção para planejamento, replanejamento, segurança, code review ou auditoria em problemas excepcionalmente difíceis |
+
+Regras adicionais:
+
+- \`xhigh\` é aceito pelo framework automático, mas permanece inelegível para trabalho comum.
+- \`xhigh\` e \`high\` não devem ser defaults de implementação extensa.
+- \`xhigh\` pode ser selecionado automaticamente somente quando os critérios de elegibilidade forem satisfeitos; os evals devem calibrar os gatilhos sem liberar uso genérico.
+- \`high\` e \`xhigh\` devem receber contexto e saída delimitados para evitar turnos abertos e excessivamente longos.
+- \`max\` não pertence à primeira versão automática e \`ultra\` é explicitamente inválido no modo \`auto\`.
+
+## Velocidade por origem
+
+Modelo e effort podem variar entre Agent Runs, nunca entre Calls da mesma Run. A origem da Execution define quem controla a velocidade:
+
+| Origem | Modelo e effort | Velocidade | Execução Fast |
+| --- | --- | --- | --- |
+| Conversation | seleção manual do Codex | seleção manual do Codex | não é execução de produto |
+| Task-first | seleção manual do Codex | seleção manual do Codex | somente por seleção manual no Codex |
+| SPEC | política automática ZAIP | sempre \`standard\` | não suportada |
+| PRD | política automática ZAIP | sempre \`standard\` | não suportada |
+
+No modo \`auto\`, toda Run de PRD ou SPEC solicita velocidade \`standard\`, e nenhum override de Task, PreparedPlan ou Execution pode mudá-la durante sua vigência. Tasks descendentes não podem escapar dessa regra. O \`service_tier\` efetivo retornado pelo host/provider continua sendo registrado como observação, mas não altera \`default_velocity\` nem retroalimenta o seletor.
+
+Selecionar Fast manualmente no Codex afeta somente Conversation ou Task-first, conforme o estado do host. O ZAIP não muda o seletor, não grava Fast em configuração persistente e não propaga a seleção para uma futura Execution de PRD ou SPEC. Se um trabalho urgente exige a DAG ou os gates parentais de uma SPEC/PRD, ele continua em \`standard\`; não fragmente artificialmente o macro em Task-first apenas para obter mais velocidade.
+
+## Separação entre risco e complexidade
+
+O ZAIP usa duas classificações independentes:
+
+- risco: \`lite\`, \`standard\`, \`critical\`;
+- complexidade: \`simple\`, \`standard\`, \`complex\`.
+
+O risco governa verificação e proteção. A complexidade influencia modelo e effort.
+
+| Risco | Gates mínimos esperados |
+| --- | --- |
+| \`lite\` | verificação scoped e Acceptance Criteria aplicáveis |
+| \`standard\` | testes dos packages afetados, revisão e evidência |
+| \`critical\` | verificação completa, revisão independente, segurança quando aplicável, rollout e rollback |
+
+Uma Task \`critical\` e mecânica pode ser executada em Terra \`medium\`, desde que receba gates críticos. Uma Task de risco \`standard\`, mas altamente ambígua e transversal, pode exigir Sol \`medium\` ou \`high\` no planejamento.
+
+## Política por agente
+
+O agente define um baseline, nunca a decisão inteira. A política combina papel, fase e metadados da Task quando o Agent Run começa:
+
+O catálogo mantém IDs internos estáveis como \`agent-builder\`, enquanto o adapter Codex os registra como \`zaip-agent-builder\`. O nome exibido vem de \`codex_task_name\` e coincide com o único \`nickname_candidates\`: \`nome_funcao_por_extenso_zaip_agent\`, sem repetir o cargo técnico. O adapter configura \`max_depth = 2\` e \`max_concurrent_threads_per_session = 5\`: essa é capacidade estrutural da squad, não permissão para executar cinco Tasks. A execução autônoma começa com uma Task e só eleva até três ramos realmente independentes.
+
+| Agente | Configuração-base | Elevação típica |
+| --- | --- | --- |
+| \`agent-orchestrator\` | Terra \`low\` | Sol \`medium\` para DAG complexa; \`high\` para síntese final crítica |
+| \`agent-builder\` | Terra \`medium\` | Sol \`medium\` para arquitetura, segurança ou migração |
+| \`agent-reviewer\` | Terra \`medium\` no catálogo | Sol quando a política e os sinais da revisão justificarem elevação; \`high\` para revisão complexa delimitada |
+| \`agent-integrator\` | Terra \`medium\` | Sol \`medium\` somente quando outra regra explícita exigir raciocínio transversal |
+| \`agent-auditor\` e \`agent-security-auditor\` | Sol \`high\` | \`xhigh\` apenas quando elegível e medido |
+| \`agent-finalizer\` | Terra \`medium\` | sem elevação automática; avalia evidência já produzida |
+| fallback \`codex\` | Terra \`medium\` | resolver novamente pela Task e pelos gates |
+
+Se nenhum agente do catálogo for selecionado, o nome do cliente/host é usado como fallback de identidade. No Codex:
+
+\`\`\`yaml
+agent: codex
+client: codex
+provider: openai
+\`\`\`
+
+\`agent\`, \`client\` e provider de inferência são dimensões diferentes. O fallback de agente continua \`codex\`; a inferência dos modelos GPT-5.6 usa provider \`openai\`. Identidade do agente e configuração do modelo são decisões separadas.
+
+## PRD e SPEC
+
+### PRD
+
+Use \`medium\` para descoberta e primeiro rascunho. Use \`high\` quando o PRD tiver múltiplos stakeholders, trade-offs relevantes ou várias SPECs. Reserve \`xhigh\` para uma passagem final em PRDs críticos que governem múltiplas SPECs, decisões de alto custo de reversão, compliance, segurança ou rollout complexo.
+
+### SPEC
+
+A SPEC tem maior potencial de retorno para reasoning elevado porque seus erros se propagam para DAG, Tasks e implementação. Use \`high\` em SPECs transversais ou arquiteturais. Uma passagem final \`xhigh\` pode ser elegível quando houver:
+
+- frontend, backend e persistência ou infraestrutura;
+- mudança de contrato de API;
+- múltiplos módulos dependentes;
+- migração e compatibilidade temporária;
+- autenticação, autorização, segurança ou dados críticos;
+- rollout e rollback complexos;
+- muitas Tasks paralelas ou locks relevantes;
+- rework anterior causado por falha de arquitetura;
+- Acceptance Criteria difíceis de transformar em testes.
+
+### Fluxo econômico de planejamento
+
+\`\`\`text
+Descoberta e rascunho       -> Terra ou Sol medium
+Estruturação do PRD/SPEC    -> Sol high, quando complexo
+Crítica e consolidação final -> Sol xhigh, somente quando elegível
+Execução da DAG             -> Luna low ou Terra medium
+Auditoria final             -> Sol medium ou high
+\`\`\`
+
+O melhor uso de \`xhigh\` é como crítico final de um documento já estruturado, não como autor a partir de uma página em branco. O turno deve receber Requirements, Acceptance Criteria, decisões, restrições, contratos, riscos, testes, rollout e rollback. A saída deve ficar limitada a contradições, lacunas, riscos, correções e decisão de prontidão.
+
+## DAG e múltiplas Tasks
+
+O resolvedor executa antes de cada Task pronta e novamente quando uma etapa materialmente distinta abre outro Agent Run:
+
+\`\`\`text
+Task pronta
+-> resolver agente
+-> resolver modelo e effort
+-> validar capacidades do modelo
+-> iniciar Agent Run
+-> registrar configuração solicitada
+-> executar e verificar
+-> registrar configuração efetiva
+\`\`\`
+
+Se Tasks paralelas exigirem configurações diferentes, cada uma deve usar Agent Run isolada. Em uma mesma thread sequencial, cada nova Run recebe explicitamente modelo e effort para impedir herança acidental da configuração anterior.
+
+Para PRDs, o runtime materializa Executions-filhas somente quando as dependências permanecem dentro da SPEC e os write scopes são globalmente disjuntos. Cada filha recebe Agent Runs, estado, orçamento e handoff próprios. O pai aguarda os terminais, integra os commits sem reexecutar Tasks e aplica validação cross-SPEC antes do finalizer; ramos inelegíveis permanecem em sua DAG global.
+
+## Rework e escalada
+
+Comece na configuração mais barata considerada segura:
+
+\`\`\`text
+Luna low -> Terra medium -> Sol medium -> Sol high -> Sol xhigh
+\`\`\`
+
+Eleve apenas um nível por vez, em novo turno, quando houver:
+
+- ambiguidade material não resolvida;
+- falha de teste após tentativa válida de correção;
+- conflito arquitetural ou entre módulos;
+- finding de segurança;
+- rejeição do reviewer;
+- invalidação do PreparedPlan por aumento de complexidade;
+- evidência insuficiente para Acceptance Criteria;
+- rework estrutural causado por dependência, contrato, sequência, migração ou escopo.
+
+Não eleve por erro de sintaxe, teste localizado, código gerado, refatoração repetitiva ou simples quantidade de arquivos.
+
+### Elegibilidade para xhigh
+
+Exija as quatro condições:
+
+1. alta complexidade ou ambiguidade arquitetural;
+2. alto custo esperado de rework;
+3. efeito transversal ou crítico;
+4. turno delimitado de planejamento, replanejamento ou auditoria.
+
+Além disso, exija pelo menos dois gatilhos observáveis:
+
+- frontend, backend e persistência ou infraestrutura;
+- três ou mais módulos com contratos compartilhados;
+- migração, segurança, autenticação ou dados críticos;
+- rollout parcial e rollback necessário;
+- dois ciclos de reparo falharam pela mesma causa estrutural;
+- finding arquitetural do reviewer;
+- PreparedPlan invalidado;
+- alternativas arquiteturais com trade-offs materiais.
+
+Os números são critérios operacionais iniciais do ZAIP, não limites publicados pela OpenAI. Eles devem ser recalibrados por evals.
+
+## Medição e break-even
+
+O KPI principal é \`tokens totais até entrega verificada\`:
+
+\`\`\`text
+custo total = planejamento
+            + implementação
+            + testes e diagnóstico
+            + revisão e auditoria
+            + ciclos de reparo
+\`\`\`
+
+O break-even de \`xhigh\` é:
+
+\`\`\`text
+custo adicional do planejamento xhigh / custo médio de um ciclo de rework
+\`\`\`
+
+Se \`xhigh\` adicionar \`E\` tokens ao planejamento e um ciclo médio de rework custar \`R\`, ele precisa evitar ao menos \`E / R\` ciclos por Task para empatar em tokens. Latência, custo monetário e criticidade continuam como guardrails separados.
+
+### Métricas obrigatórias
+
+- sucesso da Task e dos Acceptance Criteria;
+- tokens totais e tokens de reasoning;
+- latência total até conclusão;
+- custo total até entrega verificada;
+- aprovação na primeira revisão;
+- quantidade de repair cycles;
+- findings arquiteturais e de segurança;
+- falhas de integração;
+- invalidações do PreparedPlan;
+- completude das evidências;
+- bugs encontrados depois da entrega.
+
+### Piloto recomendado
+
+Compare \`Sol high\` e \`Sol xhigh\` somente no planejamento, mantendo execução e revisão iguais:
+
+\`\`\`text
+Grupo A: planejamento Sol high  -> execução Terra medium -> revisão Sol medium
+Grupo B: planejamento Sol xhigh -> execução Terra medium -> revisão Sol medium
+\`\`\`
+
+Ative \`xhigh\` para uma classe de trabalho somente quando o grupo correspondente demonstrar ganho de qualidade ou confiabilidade que compense tokens, custo e latência adicionais.
+
+## Contrato de configuração automática
+
+A configuração automática usada pelo projeto é:
+
+\`\`\`yaml
+model_orchestration:
+  mode: auto
+  default_model: gpt-5.6-terra
+  default_effort: medium
+  default_velocity: standard
+  allowed_models:
+    - gpt-5.6-luna
+    - gpt-5.6-terra
+    - gpt-5.6-sol
+  allowed_efforts:
+    - low
+    - medium
+    - high
+    - xhigh
+  max_auto_effort: xhigh
+  automatic_sources:
+    - spec
+    - prd
+  notice: mismatch
+\`\`\`
+
+Projetos novos continuam em \`manual\` até o rollout provar qualidade e custo. A mudança para \`auto\` é opt-in por projeto e por origem; \`task\` é rejeitado pelo schema. Rollback consiste em voltar para \`manual\`, sem reescrever Runs anteriores.
+
+Um novo PreparedPlan de PRD/SPEC não declara apenas \`risk: standard\`. Cada blueprint fornece \`model_signals\`, e \`createPreparedPlanV2\` calcula e persiste \`model_profile.risk\`, \`risk_policy_version: task-risk-v1\` e \`risk_reasons\`. Uma declaração de risco conflitante falha; PreparedPlans históricos sem perfil continuam legíveis, mas não entram em execução automática sem perfil.
+
+\`\`\`yaml
+model_signals:
+  phase: implementation
+  complexity: complex
+  transversality: cross_system
+  ambiguity: high
+  rework: none
+  rework_cost: high
+  bounded: true
+  high_volume: false
+  xhigh_triggers:
+    - shared_contracts_3_plus
+    - rollout_and_rollback
+  risk_signals:
+    production_impact: false
+    external_action: false
+    irreversible_change: false
+    security_or_critical_data: true
+    data_migration: false
+    broad_audit: false
+    rollback: planned
+    verification_scope: full
+\`\`\`
+
+O classificador retorna \`critical\` para impacto explícito em produção, ação externa, irreversibilidade, segurança/dados críticos, migração, auditoria ampla, rollback complexo, ambiguidade \`high\` transversal ou rework estrutural de alto custo. Retorna \`lite\` somente para trabalho simples, local, delimitado, reversível e com verificação scoped; todo caso restante é \`standard\`, sempre com motivo enumerado.
+
+O PreparedPlan pode declarar um override da Execution e cada Task pode sobrescrever campos:
+
+\`\`\`yaml
+policy:
+  runtime_defaults:
+    client: codex
+    provider: openai
+    model: gpt-5.6-terra
+    reasoning_effort: medium
+
+blueprints:
+  tasks:
+    - id: TASK-IMPLEMENTAR
+      runtime:
+        model: gpt-5.6-terra
+        reasoning_effort: medium
+
+    - id: TASK-AUDITAR
+      runtime:
+        model: gpt-5.6-sol
+        reasoning_effort: high
+\`\`\`
+
+Precedência executada:
+
+\`\`\`text
+policy.runtime_defaults explícito da Execution
+-> runtime explícito da Task
+-> política automática por perfil, fase e agente
+-> defaults do projeto
+\`\`\`
+
+O runtime anuncia modelos, efforts e velocidades antes do dispatch. Modelo fora da allowlist, effort desconhecido, \`ultra\`, \`max\`, velocidade diferente de \`standard\` ou capacidade incompatível produzem erro tipado; não existe fallback silencioso.
+
+Quando a seleção foi registrada, o cabeçalho da Run ou Sub-Run preserva a configuração resolvida e \`model.selection.recorded\` registra a decisão antes do dispatch; o default do catálogo não pode substituir o modelo realmente invocado. Telemetria efetiva e Calls conhecidas permanecem dentro da mesma chamada de agente. Capturas terminais sem metadados ricos mantêm modelo e effort indisponíveis; não devem receber uma seleção reconstruída. Run raiz é a chamada do orquestrador e possui \`parent_run_id: null\`; Sub-Run possui pai:
+
+\`\`\`yaml
+agent_run:
+  run_id: RUN-EXEC-TASK-BUILD-1
+  run_kind: sub_run
+  run_purpose: execution
+  parent_run_id: RUN-EXEC-TASK-ORCHESTRATOR
+  client: codex
+  provider: openai
+  agent: agent-task-executor
+  agent_name: zaip-agent-task-executor
+  requested_model: gpt-5.6-terra
+  requested_reasoning_effort: medium
+  effective_model: gpt-5.6-terra
+  effective_reasoning_effort: medium
+  call_count: 3
+  tokens: 42000
+  cost_brl: 1.84
+  selection_source: execution-override
+  selection_reasons:
+    - execution-override
+    - terra-implementation-baseline
+\`\`\`
+
+Requested e effective não devem ser confundidos, pois o runtime ou serviço pode aplicar fallback ou reroteamento. \`effective_*\` só pode ser preenchido por fonte observada; ausência dessa fonte não autoriza copiar \`requested_*\`.
+
+No dashboard, Runs e Sub-Runs são separados por \`parent_run_id\` e ordenados por \`started_at\` decrescente, independentemente do shard físico da projeção. A Run raiz usa a identidade visível \`zaip-agent-orchestrator\`; Sub-Runs usam o \`zaip-agent-*\` efetivamente selecionado. O Monitor de Custos agrupa e filtra pela identidade visível, mantém o modelo configurado de cada chamada em destaque e mostra o modelo efetivo separadamente. Quando o host não informou a configuração planejada, o modelo efetivo é rotulado como observado, nunca apresentado como se tivesse sido selecionado pelo catálogo.
+
+### Calls como telemetria interna
+
+O dashboard cria visões separadas para Runs e Sub-Runs, mas não cria entidade ou aba separada para Calls. Quando o host fornece eventos por \`invocation_id\`, o ledger os conserva dentro da respectiva Run/Sub-Run para calcular:
+
+1. quantidade de Calls conhecida e quantidade terminal;
+2. falhas, cancelamentos, retries e latência observáveis;
+3. modelo, effort e service tier efetivos;
+4. tokens e custo agregados na Run;
+5. divergência requested/effective sem dupla contagem.
+
+Todas as Calls da mesma Run reutilizam a configuração planejada. Se o provider aplicar fallback, a diferença aparece como configuração efetiva observada e não muda o cabeçalho. Valores indisponíveis permanecem \`null\`; prompt e reasoning privado nunca são armazenados.
+
+## Garantias implementadas
+
+1. \`project.yaml\` possui branch \`auto\` estrito e mantém \`manual\` como default de distribuição.
+2. \`automatic_sources\` restringe a política a \`spec\` e \`prd\`; o schema rejeita \`task\`.
+3. Novos PreparedPlans de PRD/SPEC calculam risco e motivos a partir de sinais persistidos; planos históricos permanecem legíveis.
+4. O coordenador injeta a política somente em Executions elegíveis e resolve novamente no início de cada Agent Run de Task/fase.
+5. A captura de conversa registra o modelo explicitamente observado ou \`unknown\`; modelo e effort efetivos não são inferidos a partir do baseline automático, do catálogo ou de uma Task avulsa.
+6. O resolvedor determinístico aplica allowlist, capacidades, overrides e motivos observáveis antes do dispatch.
+7. Testes cobrem a matriz de risco/modelo/effort, precedência, capacidades, rejeições e atribuição sem inferência.
+8. O ledger rejeita Calls com modelo, effort ou decisão de seleção solicitados diferentes dentro da mesma Agent Run.
+9. O Sub-Run registra no cabeçalho e no ledger a seleção realmente enviada ao runtime.
+10. CLI, Rules, adapters e templates distribuídos descrevem a mesma fronteira.
+
+## Não objetivos da primeira automação
+
+- aceitar \`ultra\` no modo automático;
+- usar \`max\` como default;
+- selecionar ou sobrescrever velocidade diferente de \`standard\`;
+- mudar modelo ou effort dentro de uma Agent Run;
+- criar uma tela ou lifecycle independente para Calls;
+- escolher \`high\` ou \`xhigh\` apenas por quantidade de arquivos;
+- substituir testes, reviewer ou auditor por reasoning mais alto;
+- inferir configuração ausente pelo comportamento do modelo;
+- otimizar somente o custo do primeiro turno e ignorar rework.
+
+## Referências oficiais
+
+- [GPT-5.6: seleção de modelo e effort](https://developers.openai.com/api/docs/guides/latest-model#update-api-and-model-parameters)
+- [Reasoning effort](https://developers.openai.com/api/docs/guides/reasoning#reasoning-effort)
+- [Modelos do Codex](https://learn.chatgpt.com/docs/models#pick-a-reasoning-effort)
+- [Codex App Server](https://learn.chatgpt.com/docs/app-server)
+- [Subagentes: escolha automática de modelos e reasoning](https://learn.chatgpt.com/docs/agent-configuration/subagents#choosing-models-and-reasoning)
+- [Configuração e precedência do Codex](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)
+- [Checklist de deployment e comparação por custo por sucesso](https://developers.openai.com/api/docs/guides/deployment-checklist#choose-a-gpt-56-model)
+
+As referências oficiais orientam usar o menor effort que atinja a qualidade necessária, começar em \`medium\` para equilíbrio e reservar \`high\` ou \`xhigh\` para ganho de qualidade medido. A política operacional deste guia deve continuar sendo validada pela telemetria e pelos evals do ZAIP.
+`,E=`# Auditoria do cálculo de custo equivalente via API
+
+Este documento usa o snapshot versionado em \`.agents/config/pricing/models.json\`; não declara que as tarifas ou a cotação de exemplo são atuais fora desse snapshot.
+
+## Objetivo e limite
+
+O Monitor de Custos estima quanto as **mesmas métricas de uso observadas** custariam na OpenAI API. Não é uma fatura, não mede o consumo da assinatura ChatGPT/Codex e não pode ser usado para reconciliar créditos sem dados de billing mode e rate card aplicáveis.
+
+## Separação obrigatória
+
+| Sistema | Unidade | Pode virar USD? | Regra usada no Monitor |
+| --- | --- | --- | --- |
+| Codex autenticado com ChatGPT | créditos/limites | Não automaticamente | Tokens são preservados; não se infere cobrança da assinatura. |
+| OpenAI API | USD por milhão de tokens | Sim | Estimativa equivalente com o catálogo versionado. |
+
+O Fast do Codex é consumo de créditos da assinatura e não prova que uma requisição API foi atendida em Priority. Para esta estimativa equivalente, porém, uma Run marcada Fast usa a tarifa API Priority como **cenário hipotético para reproduzir a velocidade**, sem multiplicar tokens e sem ser apresentada como cobrança API efetiva.
+
+## Invariantes de telemetria
+
+O Monitor de Custos preserva a disponibilidade por métrica. Custo equivalente só é calculado quando os tokens, a identidade de preço e a tarifa necessária estão disponíveis. Lifecycle e telemetria parcial continuam visíveis com lacunas explícitas. \`null\` permanece \`Indisponível\`; nunca é convertido em zero. A projeção pode mostrar duração reconciliada, inferida ou estimada com proveniência, mas isso não é duração observada nem comprova uma medição da chamada.
+
+\`\`\`text
+cached_input <= input
+reasoning <= output
+total = input + output
+\`\`\`
+
+Cache é parte do input; reasoning é parte do output. Ambos são campos analíticos e nunca entram uma segunda vez no total ou no custo.
+
+## Fórmula API
+
+Para uma Run com tarifas resolvidas, em USD por 1M tokens:
+
+\`\`\`text
+input_sem_cache = input - cached_input
+USD_input = input_sem_cache / 1_000_000 × tarifa_input
+USD_cache = cached_input / 1_000_000 × tarifa_cache
+USD_output = output / 1_000_000 × tarifa_output
+USD_total = USD_input + USD_cache + USD_output
+BRL_total = USD_total × cotação_USD_BRL
+\`\`\`
+
+A conversão para BRL é a última etapa. Quando a moeda exibida é USD, não há conversão.
+
+## Exemplo didático — GPT-5.6 Sol, Standard
+
+No snapshot local consultado durante a redação, \`gpt-5.6-sol\` contém input US$5, cache US$0,50 e output US$30 por 1M. Esses números ilustram a fórmula; confira o catálogo e a fonte registrada antes de usar valores em uma decisão atual. Para 1.000.000 input, 800.000 cache, 100.000 output e 70.000 reasoning:
+
+\`\`\`text
+input sem cache = 1.000.000 - 800.000 = 200.000
+input = 0,2 × 5,00 = US$ 1,00
+cache = 0,8 × 0,50 = US$ 0,40
+output = 0,1 × 30,00 = US$ 3,00
+reasoning = US$ 0,00 adicional (já está nos 100.000 output)
+total = US$ 4,40
+\`\`\`
+
+Com uma cotação **hipotética** USD/BRL de 5,45: \`4,40 × 5,45 = R$ 23,98\`.
+
+## Service tier, contexto e dados incompletos
+
+- \`priority\` seleciona a tabela Priority oficial do modelo; não multiplica tokens. \`fast\` do Codex também seleciona essa tabela somente como cenário equivalente e deve ser rotulado como derivado de Fast.
+- Priority e contexto longo sem tarifa oficial combinada retornam custo indisponível, em vez de uma multiplicação inventada.
+- Regras de contexto longo só são usadas para modelos cujo catálogo traz limiar e tarifas publicadas.
+- Modelo sem correspondência, provedor incompatível ou tarifa ausente retorna \`null\` para custo.
+- Runs históricas sem billing mode, snapshot ou tier efetivo não comprovam uma cobrança; se faltarem os componentes exigidos pelo cálculo, o custo equivalente permanece indisponível.
+
+## Auditoria por Run
+
+Na aba Runs, confirme nesta ordem: fonte do modelo efetivo, velocidade observada, **Cenário velocidade API**, input, cache, output, reasoning, tarifas selecionadas, USD e BRL. Modelo/effort sem fonte observada permanecem indisponíveis. \`Priority (derivado de Fast)\` significa cenário de estimativa, não cobrança API comprovada. \`USD/BRL registrado\` e \`BRL registrado\` são fotografia histórica quando existirem; uma estimativa em BRL deve identificar a cotação usada, sem apresentá-la como valor atual por padrão.
+
+## Prova real agregada por modelo
+
+A aba **Modelos** não lista Runs. Cada linha agrega todas as Runs do modelo dentro dos filtros ativos. Ela soma input, cache, entrada sem cache, output, reasoning, output visível, total de tokens e cada componente em USD, inclusive \`USD Standard\`, acréscimo de velocidade, estimativa e valores registrados.
+
+As tarifas exibidas ali são **efetivas ponderadas**, não uma média simples: \`USD do componente × 1.000.000 / tokens cobráveis do componente\`. Assim, a taxa reproduz exatamente o custo agregado mesmo quando o modelo tiver Runs com contextos ou tarifas diferentes. Contexto, multiplicador de velocidade e cenário mostram \`Misto\` quando não forem uniformes; o dashboard não inventa uma média para multiplicadores.
+
+Para conferir a soma: \`USD estimado API = USD entrada + USD cache + USD saída + USD raciocínio\`; no snapshot local usado pela implementação, reasoning é parte de output e o componente adicional é zero quando \`reasoning_billed_separately\` é falso. O câmbio efetivo é \`BRL estimado / USD estimado\`, calculado somente depois da soma em USD.
+
+## Implementação e testes
+
+- Catálogo: \`.agents/config/pricing/models.json\`
+- Cálculo: \`packages/costs/src/pricing-math.ts\` e \`packages/costs/src/index.ts\`
+- Projeção: \`.agents/dashboard/modules/cost-monitor/src/server/build-cost-monitor-projection.ts\`
+- Testes: \`pnpm --filter @zaip-ai/costs test\` e \`pnpm --filter @zaip-ai/dashboard-cost-monitor test\`
+`,D=`# Fontes oficiais de preços OpenAI
+
+Registro local de consulta em 15 de julho de 2026. Valores operacionais ficam no catálogo versionado \`.agents/config/pricing/models.json\`; esta página preserva as fontes usadas naquele registro, não confirma preços atuais sem nova consulta.
+
+| Tema | Fonte oficial | Uso na implementação |
+| --- | --- | --- |
+| Tarifas API Standard, Batch, Flex e Priority | https://developers.openai.com/api/docs/pricing | Seleção de tarifa por modelo e \`service_tier\` efetivo. |
+| Créditos Codex por input, cache e output | https://learn.chatgpt.com/docs/pricing#what-are-tokens-and-credits | Referência separada; não é convertida automaticamente para USD. |
+| Velocidade do Codex | https://learn.chatgpt.com/docs/agent-configuration/speed | Fast é uma regra de créditos Codex; no Monitor ele pode alimentar o cenário API Priority, explicitamente como hipótese de equivalência de velocidade. |
+| Referência Responses | https://developers.openai.com/api/reference/resources/responses/methods/create | \`service_tier\` retornado representa o modo que efetivamente atendeu a requisição. |
+
+## Regras de atualização
+
+1. Consulte novamente a fonte oficial e registre a data/hora da nova consulta; não promova esta tabela histórica a estado atual.
+2. Atualize o catálogo em uma alteração separada e registre o snapshot/versão quando disponível.
+3. Inclua testes com input, cached input e output.
+4. Não crie tarifa para uma combinação que a tabela oficial não publique.
+5. Não transforme créditos Codex em USD sem uma regra oficial explícita.
+6. Preserve modelo, tier e effort efetivos como indisponíveis quando não forem retornados por fonte observada; defaults de configuração não os substituem.
+`,O=`# Qualidade e qualificação de release
+
+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.
+
+## Cobertura
+
+\`pnpm test:coverage\` mede os módulos de domínio e aplica um ratchet versionado:
+
+- 80% de lines;
+- 80% de functions;
+- 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.
+
+## Gates agregados e diagnósticos
+
+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.
+
+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.
+
+## 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.
+
+## Evidência e aprovação
+
+Testes passando comprovam validação técnica. Maturidade formal máxima exige ainda:
+
+- SHA candidato imutável;
+- reviewer independente do autor;
+- ambiente representativo identificado;
+- observação de produção ligada ao mesmo SHA;
+- CI terminal correspondente ao commit publicado.
+
+Ausência de uma dessas provas permanece explícita; não é convertida em sucesso.
+`,k=`# 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. 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
+
+\`\`\`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\`. 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
+
+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. 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\`.
+
+## 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.
+`,A='# Lifecycle de Conversations, Tasks, SPECs e PRDs\n\nEste 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.\n\n## Classificação de entrada\n\nAliases 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.\n\n`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`.\n\n## Criação completa de PRD e SPEC\n\n“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.\n\nUse 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.\n\nAntes 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.\n\n| Entrada | Quando usar | Cria Task? | Estado inicial visível |\n| --- | --- | --- | --- |\n| Conversation | Pergunta, feedback, status ou análise pontual read-only; cria Execution `interaction` | Não | Sem card |\n| Task avulsa executável | Pedido direto de alteração ou resultado independente | Sim | Execução antes da primeira mutação |\n| Task avulsa preparada | Pedido explícito de planejamento sem autorização de executar | Sim | Pronto para Executar |\n| SPEC | Entrega técnica com múltiplos blueprints ou DAG | Tasks em `ready|execute` | Planejamento enquanto `draft` |\n| PRD | Definição de produto organizada em SPECs independentes | Tasks em `ready|execute` | Definição enquanto `draft` |\n\nConversa 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.\n\nSã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.\n\n## Colunas do Kanban\n\n| Coluna | Regra |\n| --- | --- |\n| Definição | Exclusiva de PRD `draft` |\n| Planejamento | Exclusiva de SPEC `draft` |\n| Pronto para Executar | PRD/SPEC `ready` e toda Task `planned` nunca iniciada ou tentada, avulsa ou vinculada a SPEC |\n| Execução | Task `executing`; SPEC/PRD `active` |\n| Verificação | Task `verifying` ou macro executando gates parentais |\n| Concluído | Task `completed` ou macro `delivered` |\n| Bloqueado | Resultado retomável com condição objetiva |\n| Falhado | Erro técnico impeditivo; exige rework |\n| Cancelado | Cancelamento humano explícito e imutável |\n\nActivity local nunca prevalece sobre um status final persistido. Uma invocação obsoleta não pode reviver Task concluída, bloqueada, falhada ou cancelada.\n\n## Trabalho, Execution, Run, Sub-Run e Call\n\nAs cinco camadas possuem responsabilidades diferentes:\n\n| Camada | Responsabilidade |\n| --- | --- |\n| Trabalho | Task, SPEC ou PRD que descreve o resultado e seu lifecycle |\n| Execution | `interaction` registra uma conversa; `delivery` coordena Task, Change e DAG quando aplicável |\n| Run | Chamada raiz do `zaip-agent-orchestrator`; possui `parent_run_id: null` |\n| Sub-Run | Chamada de subagente feita dentro da Run; possui `parent_run_id` |\n| Call | Invocação interna de modelo LLM; herda a configuração da Run/Sub-Run |\n\nRun 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`.\n\nCada 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.\n\nQuando 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`.\n\n### Barreira do finalizador\n\nCada 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`.\n\nO 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`.\n\nNo 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.\n\nO 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.\n\nUma observação por AC não altera esse lifecycle nem substitui os gates. Ela é\numa declaração versionada cujo vínculo só pode complementar Evidence quando\n`confirmed` e coerente; os demais estados preservam pendência ou falha. Veja o\n[contrato de prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).\n\nExemplo:\n\n```bash\nzaip run finish RUN-ID \\\n  --status completed \\\n  --task-outcome blocked \\\n  --summary "Gate de integração pendente"\nzaip run closure RUN-ID\n```\n\n## Fechamento e retomada de Tasks\n\nAntes de uma Run raiz terminar, sua Task deve estar em um destes estados:\n\n- `completed`: resultado e gates aprovados;\n- `blocked`: inconclusão retomável, dependência externa ou gate insuficiente;\n- `failed`: erro técnico/integridade que impediu a execução válida;\n- `cancelled`: pedido humano explícito.\n\n`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.\n\nInterromper a geração é uma interrupção retomável e resulta em `blocked`. “Cancelar a Task” é uma decisão explícita e resulta em `cancelled`.\n\n## Agregação de SPEC e PRD\n\nQuando 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.\n\n- Task bloqueada/falhada mantém o macro em Execução para que outras Tasks e decisões parentais continuem.\n- SPEC/PRD aguardam todas as Tasks e Runs filhas.\n- Depois que todas as Tasks concluem, o macro entra em Verificação.\n- Delivery exige gates, integração, Acceptance Criteria, outcomes e Evidence próprios do pai.\n\n## Reconciliação manual\n\nO 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.\n\nO algoritmo é idempotente e conservador:\n\n- `task_complete` local exato permite finalizar tecnicamente a Run e tentar os gates;\n- gate insuficiente produz `blocked`, nunca sucesso inventado;\n- Run sem invocação ativa por dez minutos é órfã e termina como `failed`;\n- `cancelled` nunca é inferido;\n- Tasks apenas prontas, sem Run terminal atribuída, não são reavaliadas como travadas.\n\nO 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.\n\n## Projeção no dashboard\n\nEm 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.\n\nTrabalho 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.\n\nCada 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.\n\n## Persistência compacta da telemetria\n\nMicroeventos observáveis do Codex são sanitizados e gravados primeiro no spool local ignorado pelo\nGit. Depois de um terminal ou erro, eles são compactados em um `InvocationSummaryV1` por invocação\nde agente. Os summaries são organizados em chunks imutáveis e manifestos mensais por writer em\n`.agents/records/telemetry/<ano>/<mês>/writers/<writer-id>/`.\n\nEssa compactação não substitui o ledger `RUN-*`: a Run continua sendo a fonte de lifecycle,\natribuição e evidência. O summary é a fonte compacta de métricas observadas. O Dashboard combina as\nduas leituras sem dupla contagem; tokens e custos do summary são autoritativos quando válidos, mas\numa duração delimitada do lifecycle é preservada se a fonte compacta não conhece a duração.\n\nCobertura é independente por métrica. Tokens, Calls, custo, duração e latência podem ter estados\ndiferentes na mesma invocação. `known_sum`, `unknown_count` e `coverage_ratio` precisam viajar\njuntos; `null` nunca é normalizado para zero. Detalhes de armazenamento, integridade, fallback e\nrecuperação estão em [Telemetria Git-native do Codex](27-telemetria-git-native.md).\n',j=e(),M=`# ZAIP-AIOS (6 Squads + 23 Agents)
+
+## Visão rápida
+
+O ZAIP-AIOS é um sistema operacional para execução autônoma de trabalho com agentes de IA, que coordena 23 agentes especializados, organizados em 6 squads, dentro do Codex.
+
+Os agentes planejam, executam, revisam, testam e validam o trabalho sob coordenação do orquestrador. A execução autorizada avança até atender aos critérios definidos ou registrar um bloqueio, falha ou limite de orçamento. Dependências externas e decisões fora da autoridade recebida continuam exigindo intervenção humana; autonomia não significa execução indefinida nem garantia de acerto.
+
+Essa abordagem busca reduzir intervenções, contexto desnecessário e retrabalho. Os percentuais de 34% e 62% apresentados adiante se referem a custo médio por tarefa e por hora nas séries históricas ilustradas, respectivamente; não medem diretamente redução de tokens nem garantem economia em uma nova entrega.
+
+Embora tenha nascido com foco em software, o ZAIP-AIOS também coordena demandas de Operações, Growth, Marketing, Branding e Vendas. O framework e o Dashboard funcionam localmente, sem exigir VPS. Autenticação, franquia, cobrança e integrações dependem do host/provider escolhido; usar uma assinatura no Codex não transforma o custo equivalente estimado em cobrança de API.
+
+<img src=".agents/config/src/Zaip%20AIOS%20Squads.png" alt="Estrutura organizacional dos seis squads e 23 agentes do ZAIP-AIOS" width="100%">
+
+Na prática, o sistema decompõe demandas complexas, organiza o trabalho, seleciona os agentes mais adequados, coordena dependências, acompanha a execução e verifica a qualidade antes de considerar uma entrega concluída.
+
+O Dashboard centraliza a operação em uma única visão, reunindo Tasks, SPECs e PRDs, além de dependências, bloqueios, tempo de execução, consumo de tokens, custos, revisões e evidências produzidas ao longo do processo.
+
+<img src=".agents/config/src/dashboard_pt_1_visao_geral.png" alt="Dashboard ZAIP-AIOS, Visão Geral" width="100%">
+
+Em uma amostra comparativa de tarefas executadas de forma autônoma, o ZAIP-AIOS apresentou uma redução aproximada de 34% no custo médio por tarefa e 62% no custo médio por hora.
+
+A comparação considera o ciclo completo de trabalho, planejamento, execução, testes, revisões e documentação —, e os resultados devem ser interpretados dentro dos limites da amostra analisada.
+
+<img src=".agents/config/src/analise_comparativa_reducao_custo_por_hora.png" alt="Análise comparativa: custo médio por hora caiu de R$ 410 para R$ 154" width="900">
+
+A fonte canônica permanece nos arquivos Git-native do repositório. Requisitos, decisões, implementações e provas podem ser versionados; só passam a estar no histórico remoto após commit e publicação explicitamente autorizada. Segredos e estado privado da máquina ficam fora desse histórico.
+
+O Dashboard utiliza um banco de dados local, descartável e reconstruível, apenas como camada de consulta e visualização. Nenhuma informação crítica depende exclusivamente dele.
+
+No ZAIP-AIOS, uma Task não é considerada concluída apenas porque um agente terminou sua execução. Ela só é encerrada quando existem evidências objetivas de que os Critérios de Aceite e os requisitos de qualidade foram atendidos.
+
+## Comece por aqui
+
+| Se você quer… | Comece por… |
+| --- | --- |
+| Instalar e obter o primeiro resultado | [Instalação em um comando](#instalação-em-um-comando) |
+| Conhecer os resultados observados | [Economia medida](#economia-medida-e-meta-central-por-tarefa) |
+| Acompanhar trabalho, custos e qualidade | [Dashboard Local](#dashboard-local) |
+| Fazer uma alteração pontual | [Três formas de executar](#três-formas-de-executar) |
+| Planejar uma entrega técnica ou de produto | [PRD como interface de autonomia](#prd-como-interface-de-autonomia) |
+| Entender o método | [Método ZAIP em seis etapas](#método-zaip-em-seis-etapas) |
+| Conhecer os agentes especializados | [Personas e roteamento de agentes](#personas-e-roteamento-de-agentes) |
+| Consultar os contratos técnicos | [Referência técnica e operacional](#referência-técnica-e-operacional) |
+| Manter o framework | [Desenvolvimento do framework](#desenvolvimento-do-framework) |
+| Configurar permissões com segurança | [Segurança com perfis de permissão](#segurança-com-perfis-de-permissão) |
+| Avaliar lançamento, suporte e comercialização | [Prontidão para produção e comercialização](docs/PRODUCTION-COMMERCIAL-READINESS.md) |
+| Navegar pelos 28 guias operacionais | [Índice completo do handbook](.agents/zaip-aios/INDEX.md) |
+
+### Como interpretar esta documentação
+
+Este README e o [handbook](.agents/zaip-aios/INDEX.md) descrevem o código-fonte deste repositório. Configuração efetiva, suporte do host, pacote instalado e candidato qualificado são dimensões distintas. \`@latest\` aponta para a versão publicada, que pode não conter alterações locais. As imagens do Dashboard são ilustrações de estados anteriores, não prova visual do candidato atual.
+
+A atualização documental não aprova uma release. Consulte o [registro de limites de qualificação](docs/PRODUCTION-COMMERCIAL-READINESS.md#limites-conhecidos-da-qualificação) antes de promover o código; testes locais, paridade, CI e validação em produção devem ser comprovados separadamente.
+
+## Instalação em um comando
+
+Com Git e uma versão compatível de Node.js, a instalação acontece na raiz do repositório que receberá o ZAIP-AIOS. O pacote declara Node.js 22+; para o Dashboard com \`node:sqlite\`, use uma versão que disponibilize esse módulo (o ambiente de referência deste checkout usa 22.16.0), não qualquer versão inicial da série 22:
+
+\`\`\`bash
+npx @zaip-ai/cli@latest init
+\`\`\`
+
+O sufixo \`@latest\` instala a release pública atual sem fixar o README a uma versão específica. O CLI encontra a raiz Git mesmo quando o comando é iniciado em uma subpasta, valida o template antes de escrever e interrompe a instalação se detectar conflito com arquivo pertencente ao usuário. O mesmo comando pode ser executado novamente para receber arquivos novos e atualizar adapters gerenciados sem apagar o histórico do projeto.
+
+Cada release do CLI leva seu próprio template verificado. A árvore documentada neste README representa o estado atual do repositório-fonte; uma funcionalidade recém-integrada passa a chegar pelo mesmo comando assim que a release correspondente é publicada.
+
+O instalador cria [\`.agents\`](.agents/) com regras, requisitos, skills, documentação operacional, catálogo de ferramentas, Dashboard, design system e estado Git-native do lifecycle. Também instala os adapters \`AGENTS.md\` e \`CLAUDE.md\`, as skills de descoberta em \`.codex/skills/zaip-aios/SKILL.md\` e \`.claude/skills/zaip-aios/SKILL.md\`, a configuração de projeto \`.codex/config.toml\` e as configurações equivalentes do Claude. Todos apontam para a mesma fonte canônica, preservando o Codex como experiência principal sem acoplar PRDs, SPECs, Tasks e evidências a um único host.
+
+Depois da instalação, o [índice operacional](.agents/zaip-aios/INDEX.md) organiza os guias de primeiros passos, execução, revisão, custos, ferramentas, diagnóstico e atualização.
+
+## Como as camadas se complementam
+
+| Tipo | Nome | Responsabilidade |
+| --- | --- | --- |
+| **Modelo de IA (AI Model)** | **GPT-5.6 (padrão)** | Modelo principal para raciocínio, programação, uso de ferramentas, coordenação de agentes e execução de tarefas complexas. A configuração permanece aberta para testes, comparação ou substituição por outros modelos. |
+| **Ferramenta (AI Harness)** | **Codex (padrão)** | Harness oficial que conecta o modelo LLM ao terminal, ferramentas, subagentes, worktrees, sandbox, hooks, skills e navegador. Por estar alinhado ao treinamento do modelo, oferece maior otimização, previsibilidade e aproveitamento de suas capacidades. |
+| **Metodologia (AI Coding)** | **ZAIP-AIOS** | Sistema Git-native de engenharia autônoma e multiagente. Converte PRDs e SPECs em Tasks, DAGs e Changes executáveis, automatiza testes e reviews e mantém decisões, execuções, evidências, custos e mudanças rastreáveis no Git. |
+
+O modelo fornece a inteligência, o Codex oferece o ambiente oficial de execução e o ZAIP-AIOS acrescenta método, governança e memória verificável. Essa combinação define **o que deve ser feito, como o trabalho deve ser organizado, quais regras precisam ser respeitadas e quais provas permitem declará-lo concluído**. A experiência de referência é otimizada para GPT-5.6 e Codex, enquanto modelos e hosts alternativos permanecem disponíveis para comparação e compatibilidade por meio de artefatos portáveis.
+
+## Personas e roteamento de agentes
+
+O ZAIP-AIOS reúne 23 agentes especializados para que cada demanda seja conduzida pela competência mais adequada. O objetivo não é usar todos em cada entrega, mas formar o menor conjunto capaz de executar, revisar e comprovar o resultado com qualidade.
+
+As identidades técnicas permanecem separadas das personas visíveis. Assim, nomes e cargos podem ser apresentados e configurados no Dashboard sem comprometer os contratos internos de roteamento. A escolha considera a decisão ou o resultado primário, especialidade, escopo e risco; referências e insumos apoiam o trabalho, mas não mudam sozinhos o executor. Autoria, contexto e histórico permanecem rastreáveis.
+
+### Os 23 agentes
+
+| Foto | # | Persona / função | Especialidade |
+| :---: | ---: | --- | --- |
+| <img src=".agents/config/src/1%20-%20Dave%20-%20Product%20Owner.png" alt="Dave, Product Owner" width="400"> | 1 | Dave / Product Owner | Resolve DAG e delega |
+| <img src=".agents/config/src/2%20-%20Rafa%20-%20Tech%20Lead.png" alt="Rafa, Tech Lead" width="400"> | 2 | Rafa / Tech Lead | Entrega genérica, SPEC e dashboard/local |
+| <img src=".agents/config/src/3%20-%20Leo%20-%20Software%20Engineer.png" alt="Leo, Software Engineer" width="400"> | 3 | Leo / Software Engineer | Task genérica ponta a ponta |
+| <img src=".agents/config/src/4%20-%20Bia%20-%20Product%20Manager.png" alt="Bia, Product Manager" width="400"> | 4 | Bia / Product Manager | Criação/refino de PRD e análise de produto |
+| <img src=".agents/config/src/5%20-%20Gui%20-%20Quality%20Assurance%20Lead.png" alt="Gui, Quality Assurance Lead" width="400"> | 5 | Gui / Quality Assurance Lead | Resultado terminal restrito |
+| <img src=".agents/config/src/6%20-%20Nanda%20-%20Principal%20Engineer.png" alt="Nanda, Principal Engineer" width="400"> | 6 | Nanda / Principal Engineer | Revisão independente |
+| <img src=".agents/config/src/7%20-%20Dani%20-%20Integration%20Engineer.png" alt="Dani, Integration Engineer" width="400"> | 7 | Dani / Integration Engineer | Integração e gates combinados |
+| <img src=".agents/config/src/8%20-%20Ana%20-%20Quality%20Auditor.png" alt="Ana, Quality Auditor" width="400"> | 8 | Ana / Quality Auditor | Auditoria independente |
+| <img src=".agents/config/src/9%20-%20Lia%20-%20Technical%20Writer.png" alt="Lia, Technical Writer" width="400"> | 9 | Lia / Technical Writer | Resumo fiel, análise de transcrição e documentação fundamentada em fontes |
+| <img src=".agents/config/src/10%20-%20Gabi%20-%20Data%20Analyst.png" alt="Gabi, Data Analyst" width="400"> | 10 | Gabi / Data Analyst | Análise de dados |
+| <img src=".agents/config/src/11%20-%20Tati%20-%20Refactoring%20Specialist.png" alt="Tati, Refactoring Specialist" width="400"> | 11 | Tati / Refactoring Specialist | Refatoração, migração e modularização seguras |
+| <img src=".agents/config/src/12%20-%20Doug%20-%20Frontend%20Developer.png" alt="Doug, Frontend Developer" width="400"> | 12 | Doug / Frontend Developer | Frontend e acessibilidade conforme \`DESIGN.md\` |
+| <img src=".agents/config/src/13%20-%20Will%20-%20Backend%20Developer.png" alt="Will, Backend Developer" width="400"> | 13 | Will / Backend Developer | API, backend e módulos |
+| <img src=".agents/config/src/14%20-%20Jonny%20-%20Website%20Developer.png" alt="Jonny, Website Developer" width="400"> | 14 | Jonny / Website Developer | Sites e landing pages, SEO, GEO e preparação para agentes |
+| <img src=".agents/config/src/15%20-%20Manu%20-%20Product%20Designer.png" alt="Manu, Product Designer" width="400"> | 15 | Manu / Product Designer | \`DESIGN.md\`, Design System, tokens e catálogo |
+| <img src=".agents/config/src/16%20-%20Dan%20-%20Cloud%20Engineer.png" alt="Dan, Cloud Engineer" width="400"> | 16 | Dan / Cloud Engineer | Infraestrutura cloud, Terraform, Docker e ambientes |
+| <img src=".agents/config/src/17%20-%20Luis%20-%20Security%20Auditor.png" alt="Luiz, Security Auditor" width="400"> | 17 | Luiz / Security Auditor | Auditoria técnica e independente de segurança |
+| <img src=".agents/config/src/18%20-%20Lucia%20-%20Marketing%20Analyst.png" alt="Lucia, Marketing Analyst" width="400"> | 18 | Lucia / Marketing Analyst | Planejamento de marketing, copy e preparação de ativos |
+| <img src=".agents/config/src/19%20-%20Renata%20-%20Compliance%20Specialist.png" alt="Renata, Compliance Specialist" width="400"> | 19 | Renata / Governance & Compliance Specialist | Artefatos internos de RH, jurídico operacional, políticas, privacidade, fornecedores e riscos |
+| <img src=".agents/config/src/20%20-%20Clara%20-%20Operations%20Specialist.png" alt="Clara, Operations Specialist" width="400"> | 20 | Clara / Operations Generalist | Documentos, apresentações, planilhas, processos e comparativos delimitados fora de especialidades obrigatórias |
+| <img src=".agents/config/src/21%20-%20Sarah%20-%20Branding%20Specialist.png" alt="Sarah, Branding Specialist" width="400"> | 21 | Sarah / Branding Specialist | Estratégia e governança de marca, Brandbook, arquétipos, diferencial semântico e arquitetura de marca |
+| <img src=".agents/config/src/22%20-%20Aaron%20-%20Sales%20Specialist.png" alt="Aaron, Sales Specialist" width="400"> | 22 | Aaron / Sales Specialist | Processo comercial interno, qualificação, playbooks, scripts e handoffs entre SDR e closer |
+| <img src=".agents/config/src/23%20-%20Robert%20-%20Growth%20Strategist.png" alt="Robert, Growth Strategist" width="400"> | 23 | Robert / Growth Strategist | Estratégia de crescimento, RevOps, experimentos e recomendações orientadas por dados e impacto financeiro |
+
+O [Catálogo de agentes](.agents/zaip-aios/guides/18-catalogo-de-agentes.md) reúne as especialidades e responsabilidades dos agentes disponíveis no ZAIP-AIOS.
+
+### Squads organizacionais
+
+<img src=".agents/config/src/Zaip%20AIOS%20Squads.png" alt="Estrutura organizacional dos seis squads e 23 agentes do ZAIP-AIOS" width="100%">
+
+Os seis squads tornam a estrutura de responsabilidades fácil de visualizar: **Product** (Dave, Bia e Manu), **Admin & Operations** (Clara, Renata e Lia), **Development** (Rafa, Leo, Jonny, Will, Doug e Tati), **Delivery Assurance** (Nanda, Gui, Ana e Dani), **Infra & Security** (Dan e Luiz) e **Growth — Sales, Marketing and Branding** (Robert, Gabi, Lucia, Sarah e Aaron).
+
+Essa é uma visão organizacional, não uma regra de roteamento. O orquestrador seleciona o agente por capability, escopo declarado, risco e write scopes da Task; pertencer ao mesmo squad não concede acesso, não substitui a seleção canônica e não obriga colaboração.
+
+Cada demanda pode começar como uma Task, uma SPEC ou um PRD. Em qualquer entrada, a intenção é transformada em trabalho estruturado, com objetivo, escopo, critérios de qualidade e etapas rastreáveis.
+
+O Codex permanece como ambiente de execução, enquanto o ZAIP-AIOS acrescenta organização, governança e visibilidade ao ciclo de desenvolvimento. Pelo Dashboard, é possível acompanhar o avanço das entregas, suas dependências, bloqueios e resultados.
+
+Quando executado com a conta ChatGPT/Codex, o consumo segue as condições dessa conta. O Dashboard apresenta, quando há telemetria e preço compatível, uma estimativa de custo equivalente de API para comparação e planejamento; outros providers podem ter modalidades próprias de cobrança.
+
+## Dashboard Local
+
+O Dashboard transforma o histórico técnico do ZAIP-AIOS em uma visão operacional clara. Em um só lugar, ele mostra o trabalho em andamento, os custos observados, a cobertura de qualidade, os bloqueios e a relação entre intenção, execução e resultado.
+
+<img src=".agents/config/src/dashboard_pt_1_visao_geral_este_mes.png" alt="Dashboard ZAIP-AIOS, Visao Geral Mes" width="100%">
+
+Os registros Git-native continuam sendo a fonte oficial. Tudo o que aparece nas telas pode ser reconstruído a partir dos arquivos canônicos e da configuração do projeto, sem criar uma base paralela ou dependência externa de infraestrutura.
+
+<strong>Como funciona a projeção local do Dashboard</strong>
+
+Os registros ZAIP canônicos permanecem na estrutura padrão em \`.agents/records\`. Para acelerar consultas e visualizações, o Dashboard reconstrói um SQLite descartável como *read model*. Esse arquivo não é fonte de verdade nem armazenamento canônico: é apenas uma projeção local reconstruível.
+
+Não é preciso instalar servidor SQLite, DBeaver ou banco externo. O runtime usa \`node:sqlite\` e mantém a projeção em \`.local/dashboard-sqlite/read-model.sqlite\`. Abrir ou atualizar o Dashboard não autoriza reconciliação global de Runs: essa operação é separada e exige confirmação.
+
+
+### Kanban
+
+Organiza PRDs, SPECs e Tasks por estágio, destacando execução, verificação, conclusão, criticidade, tempo, tokens e custo observado.
+
+<img src=".agents/config/src/dashboard_pt_2_kanban.png" alt="Dashboard ZAIP-AIOS, Kanban" width="100%">
+
+As visões Trabalho (Kanban) e Trabalho (Lista) permitem alternar entre leitura por estágio e comparação detalhada. Ambas preservam os filtros Todas as Tarefas, Visão Unificada Geral, PRDs, SPECs e Tarefas Avulsas, facilitando a análise de status, origem, risco, Runs, Sub-Runs, tempo, tokens, custo e cobertura. Cada item pode ser aberto para investigar bloqueios e consultar seu histórico rastreável.
+
+### Monitor de Custos
+
+Consolida tokens, duração, custo equivalente estimado e cobertura por período e por unidade de trabalho, sem transformar telemetria ausente em zero.
+
+<img src=".agents/config/src/dashboard_pt_3_monitor_custos.png" alt="Dashboard ZAIP-AIOS, Monitor de Custos" width="100%">
+
+O Monitor consolida tokens, tempo, custo e cobertura por Run, Task, SPEC e PRD. Isso permite comparar conversa, planejamento, execução, trabalho novo e rework, além de identificar médias e concentrações de consumo por dia, mês ou ano.
+
+Quando o Codex utiliza os tokens ou a franquia da conta em vez de cobrar uma API, o módulo calcula, sempre que há medição e pricing compatível, o **custo equivalente estimado de API** em USD e BRL. A estimativa apoia gestão e comparação, mas nunca é apresentada como cobrança real. Valores não observados continuam \`unknown\`, sem serem convertidos artificialmente em zero.
+
+**Contrato técnico da telemetria**
+
+A telemetria do Codex usa spool local sanitizado, um \`InvocationSummary\` por invocação e chunks com
+manifestos mensais rastreados pelo Git. Consultas com período usam os manifestos primeiro e mantêm
+fallback para a projeção de Run quando não existe resumo aplicável. Cobertura incompleta continua
+explícita em cada métrica. A [Telemetria Git-native do Codex](.agents/zaip-aios/guides/27-telemetria-git-native.md)
+documenta contratos, armazenamento, integridade, recuperação e limites do rollout.
+
+
+### Rastreabilidade
+
+Relaciona intenção, planejamento, execução, decisões, validações e evidências para explicar de onde cada resultado veio.
+
+<img src=".agents/config/src/dashboard_pt_4_rastreabilidade.png" alt="Dashboard ZAIP-AIOS, Rastreabilidade" width="100%">
+
+Correlaciona PRD, Requirements, SPEC, Change, Task, Execution, Runs, Decisions, testes, reviews, evals e Evidence em um grafo lógico de rastreabilidade. A visão detalha as seis etapas do método e mostra quais documentos e provas sustentam cada resultado. Cada registro recebe identificador, data e hora quando faz parte do lifecycle ou da telemetria; as evidências permanecem vinculadas e a cronologia também é preservada pelo Git. Isso permite auditoria, retomada, análise de rework e comparação entre intenção e execução. Projeções podem ser reconstruídas e otimizadas; a compactação Git-native da telemetria preserva IDs, relações, métricas, cobertura e hashes sem versionar prompts ou respostas.
+
+## Configurações do projeto
+
+O Dashboard reúne a configuração do projeto em uma tela ligada ao arquivo canônico \`.agents/config/project.yaml\`. Antes de salvar, a configuração é validada pelo schema, preservando uma definição explícita do framework, das capacidades disponíveis e da visão geral dos artefatos do projeto.
+
+### Configuração da plataforma
+
+A configuração da plataforma apresenta o estado de ativação do ZAIP-AIOS e um resumo dos agentes, squads, skills, Rules, hooks e banco de dados. A mesma visão mostra os documentos de referência do projeto e indica quais deles já existem, mantendo a configuração técnica e a documentação visíveis no mesmo contexto.
+
+<img src=".agents/config/src/dashboard_pt_configuracao_plataforma.png" alt="Dashboard ZAIP-AIOS, configuração da plataforma" width="100%">
+
+### Stack de desenvolvimento
+
+A stack de desenvolvimento descreve cada responsabilidade separadamente, com tecnologia, versão exata e referência do pacote, imagem ou serviço. No projeto, esse contrato inclui TypeScript, Node.js, Hono, Kysely, PostgreSQL via Supabase, Supabase Auth + Storage, Redis e BullMQ, permitindo que as escolhas de desenvolvimento permaneçam registradas junto da configuração do projeto.
+
+<img src=".agents/config/src/dashboard_pt_configuracao_plataforma_stack.png" alt="Dashboard ZAIP-AIOS, stack de desenvolvimento" width="100%">
+
+## O custo que importa: concluir a tarefa
+
+O preço de uma chamada ou de um modelo não representa sozinho o custo real do desenvolvimento com IA. Uma entrega pode envolver entendimento, leitura de contexto, implementação, testes, correções, revisão, validação e documentação. Por isso, o ZAIP-AIOS mede **o custo para concluir o trabalho**, acompanhando Runs, fases e rework por Task, SPEC e PRD.
+
+Uma forma prática de analisar o custo total é:
+
+\`\`\`text
+custo da tarefa concluída = modelo + ferramentas + tempo humano + rework + custo de defeitos
+\`\`\`
+
+## PRD como interface de autonomia
+
+O PRD permite governar uma iniciativa completa sem transformar cada decisão técnica em uma nova etapa manual. Ele registra o resultado esperado, organiza as entregas necessárias e mantém espaço para revisão humana antes da execução.
+
+Quando o usuário diz **“Me ajude a pensar sobre um PRD”**, o sistema mantém a interação como uma conversa de planejamento.
+
+Quando diz **“Crie um PRD”**, a IA faz até cinco perguntas importantes por turno, por no máximo três turnos. Depois, cria:
+
+- um PRD em estado \`draft\`
+- as SPECs técnicas necessárias
+- um \`PreparedPlan\`
+- uma lista resumida de Tasks
+
+As decisões técnicas que puderem ser delegadas são assumidas e registradas pela IA.
+
+**Detalhes de planejamento, decomposição e comandos**
+
+### Organização das SPECs
+
+Por padrão, cada PRD utiliza apenas uma SPEC, buscando economia.
+
+Uma nova SPEC só deve ser criada quando existir uma capacidade que possa ser implementada e validada de forma independente e paralela. Quando existe dependência entre partes do trabalho, elas permanecem na mesma SPEC e são organizadas pela DAG de Tasks.
+
+No runtime atual, um PRD materializa uma Execution-filho determinística para cada SPEC elegível: suas dependências permanecem dentro da SPEC e seus write scopes não conflitam com nenhum outro ramo. Cada filha executa com coordinator, estado, quota de orçamento e handoff próprios, sob uma fila limitada pelo paralelismo efetivo e por um ledger parental único de invocações; a Execution do PRD aguarda os estados terminais, integra os candidatos no handoff parental e só então aplica validação cross-SPEC e finalização. SPECs com dependência externa ou conflito de escopo permanecem na DAG global coordenadora.
+
+Antes de o PRD chegar ao estado \`ready\`, as Tasks são apenas definições de trabalho, ainda sem execução.
+
+Os comandos **“Deixe pronto para executar”**, **“Finalize o PRD”** ou **“Conclua o PRD”** criam as Tasks, Changes e Executions no estado \`planned\`, mas não iniciam a implementação.
+
+O comando **“Execute”** atua sobre o menor item informado pelo usuário, que pode ser uma Task, uma SPEC ou o PRD completo.
+
+### Limite de decomposição
+
+A escala de 1 a 5 define o limite de decomposição do PRD. Ela não representa uma meta obrigatória.
+
+* Nível 1 cobre um único fluxo vertical
+* Níveis 2 a 4 exigem capacidades independentes, com contratos e escopos de escrita separados
+* Nível 5 deve ser usado apenas em casos excepcionais com cinco implementações semelhantes e independentes
+
+Quando existe dependência entre capacidades, o trabalho deve permanecer na mesma SPEC. Projetos com mais de cinco capacidades devem ser divididos em outros PRDs ou registrar uma exceção.
+
+### Comportamento dos comandos
+
+O comando \`implemente\` considera o estado atual do trabalho:
+
+* sem alvo definido, abre uma Conversation de planejamento
+* em \`draft\`, conclui o plano
+* em \`ready\`, inicia a execução
+* em estados ativos ou com falha, continua, retoma ou inicia o rework
+
+Os comandos \`desenvolva\`, \`melhore\` e \`aprimore\` sempre retornam ao planejamento ou ao rework.
+
+Um PRD cancelado não pode ser alterado. Quando necessário, um novo PRD de rework é criado, preservando o vínculo e o histórico de auditoria.
+
+### Rastreamento de execução
+
+Toda criação de PRD ou SPEC é vinculada à Run responsável por meio do campo \`creation_run_id\`.
+
+Tempo, tokens e custo são agregados sempre que essas informações estiverem disponíveis ou forem reconciliadas. Quando não houver dados suficientes, os valores permanecem como \`unknown\` ou \`null\`.
+
+
+## Qualidade e evidências
+
+Qualidade faz parte da definição de pronto. Cada entrega combina testes, revisão e checks proporcionais ao seu risco, com comprovação objetiva dos Critérios de Aceite.
+
+As Evidence conectam validações aprovadas à Task, Change, Execution, Run, Critérios de Aceite e candidato. O [guia de revisão](.agents/zaip-aios/guides/07-revisao-e-validacao.md) explica como registrar o procedimento realmente executado e seu resultado.
+
+O contrato atual acrescenta observações \`confirmed\`, \`limited\`, \`pending\`, \`failed\` e \`not_applicable\`, sem substituir Validation/Evidence V2. A CLI valida estrutura e vínculos; não executa o comando declarado, não examina imagens e não consulta serviços automaticamente. Prova técnica não equivale a prova visual, integração real ou produção. Observações isoladas ou pendentes não aprovam uma entrega.
+
+Novos registros de Validation, Evidence, Observation e eventos de Run rejeitam padrões conhecidos de credenciais antes da persistência, sem repetir o valor sensível no erro. Use locators e resultados sanitizados; a proteção não certifica que um texto está livre de todo segredo ou dado pessoal. Históricos continuam legíveis e não são reescritos automaticamente.
+
+Para reduzir ciclos sem reduzir qualidade, escolha cedo o cenário que pode revelar uma direção errada. Repita após uma mudança concreta ou resultado que exija correção, não apenas porque o relógio avançou. A indisponibilidade da mesma ferramenta tem fallback finito e pendência explícita; a suficiência da prova continua sendo responsabilidade do executor/revisor. Consulte o [contrato canônico de prova observável](.agents/skills/zaip-skill-change/references/observable-evidence.md).
+
+Tests, reviews, checks e Evidence tornam a evolução do projeto mais previsível: elevam a confiança nas mudanças, facilitam revisões e mantêm decisões, validações e aprimoramentos plenamente rastreáveis.
+
+
+## Economia medida e meta central por tarefa
+
+As análises abaixo apresentam reduções de custo **medidas na amostra comparativa** sob duas perspectivas complementares: custo médio por Task e custo médio por hora. Os gráficos e a tabela detalham os valores, os cálculos e a leitura de cada indicador. Os resultados confirmam redução nas séries analisadas, mas não devem ser generalizados para toda Task, modelo ou repositório sem uma nova comparação equivalente.
+
+### Análise de custo por tarefa
+
+Este gráfico acompanha o custo de cada Task nas duas faixas comparadas. A média inicial é de **R$ 67 por tarefa**; no recorte posterior, ela passa a **R$ 44**. A redução de **34,3%** (apresentada como aproximadamente 34%) representa o custo médio menor para concluir uma unidade de trabalho na amostra observada.
+
+<img src=".agents/config/src/analise_comparativa_reducao_custo_por_tarefa.png" alt="Análise comparativa: custo médio por tarefa caiu de R$ 67 para R$ 44" width="900">
+
+### Análise de custo por hora
+
+Este gráfico apresenta a mesma comparação na perspectiva horária. A média de custo cai de **R$ 410 por hora** para **R$ 154 por hora**, uma redução de **62,4%** (aproximadamente 62%). Essa leitura complementa a análise por Task ao mostrar que a redução também se mantém quando o custo é observado por hora.
+
+<img src=".agents/config/src/analise_comparativa_reducao_custo_por_hora.png" alt="Análise comparativa: custo médio por hora caiu de R$ 410 para R$ 154" width="900">
+
+Cada indicador abaixo mede uma parte diferente do fluxo. Os percentuais não devem ser somados, pois podem refletir otimizações simultâneas na mesma execução. As métricas de contexto e payload continuam sendo medições reproduzíveis do snapshot de **18/08/2026**; elas não descrevem automaticamente a população atual de skills ou do repositório.
+
+As duas primeiras linhas são resultados financeiros observados nas séries comparativas. As demais isolam ganhos de payload e navegação que ajudam a explicar como o fluxo pode reduzir custo, ciclos e retrabalho.
+
+| O que é reduzido | O que representa | Baseline sem a otimização | Com ZAIP-AIOS | Economia | Situação da métrica |
+| --- | --- | ---: | ---: | ---: | --- |
+| **Custo médio por tarefa** | Média de custo das Tasks nas duas faixas da série comparativa. | **R$ 67** | **R$ 44** | **34%** | **Medição observada** na comparação apresentada (redução exata: 34,3%). |
+| **Custo médio por hora** | Média de custo por hora nas duas faixas da série comparativa. | **R$ 410** | **R$ 154** | **62%** | **Medição observada** na comparação apresentada (redução exata: 62,4%). |
+| **Contexto entregue ao agente para uma Task** | O pack de Rules, Requirements e artefatos relevantes que entra no prompt de trabalho. | 7.980 tokens | **1.593 tokens** | **80,0%** | Medição reproduzível. |
+| **Navegação operacional recorrente** | Uma rodada de quatro consultas para localizar Changes, Tasks, Executions e Runs ativos. | 101.924 tokens | **10.199 tokens** | **90,0%** | Medição reproduzível; também reduz o limite de paginação. |
+| **Instruções disponíveis para o agente** | Snapshot de 13/07/2026 do catálogo então consultável pelo agente (26 skills). | 1.091 tokens | **599 tokens** | **45,1%** | Medição reproduzível do snapshot; não é a contagem atual de skills. |
+
+
+### Metodologia da comparação
+
+A comprovação de economia baseia-se em coortes de Tasks equivalentes, observadas em dois cenários — por exemplo, Codex normal e Codex + ZAIP-AIOS — com o mesmo modelo, repositório, Critérios de Aceite e janela de observação. Essa equivalência mantém a comparação centrada no efeito do fluxo de trabalho.
+
+Os indicadores que compõem a análise são:
+
+- tokens e custo equivalente de API de todas as chamadas até a conclusão;
+- duração e número de ciclos/retries;
+- tempo humano de revisão e correção;
+- taxa de rework e defeitos encontrados após a entrega;
+- cobertura de testes, reviews e evidências dos Critérios de Aceite.
+
+O Cost Monitor preserva valores desconhecidos como \`unknown\`/\`null\` e não converte ausência de telemetria em custo zero. Dessa forma, os resultados mantêm visíveis custos de provider, rework ou qualidade que ainda não tenham sido observados. A metodologia e seus registros complementares estão em [a auditoria de tokens e performance](analysis/verificacao-auditoria-tokens-performance-zaip-aios-2026-07-13.md).
+
+O comando \`zaip cost cohort --input <arquivo.json> --json\` calcula coortes comparáveis a partir de custos faturados observados e sua proveniência. O contrato de cálculo exige moeda USD, fonte, timestamp, *quality floor*, tentativa terminal e uma única identidade de baseline equivalente. Na ausência ou divergência de uma dimensão obrigatória, a economia permanece \`null\`, preservando a integridade da comparação.
+
+## Comparação com os principais frameworks concorrentes
+
+Esta seção preserva um recorte histórico, não uma pesquisa de mercado atualizada nem certificação de produção. As notas abaixo não substituem a qualificação do candidato atual e não foram recalculadas nesta revisão documental.
+
+Este recorte usa uma auditoria comparativa, consolidada em 6 de agosto de 2026, e posiciona cada produto a partir dos sinais encontrados em código, configuração, arquitetura, testes e documentação. A metodologia reúne dez critérios com o mesmo peso: cada tópico recebe de 0 a 10 pontos e a nota final, de 0 a 100, é a soma direta desses resultados. Na escala adotada, 9–10 indica uma referência clara no critério; 7–8, uma proposta forte e competitiva; 5–6, uma capacidade relevante ainda parcial; e 0–4, pouca evidência ou baixa ênfase no recorte analisado. A matriz detalhada torna a composição das notas transparente e permite atualizá-las conforme os produtos evoluem.
+
+| Produto | Nota /100 | Justificativa da nota | Posicionamento competitivo |
+|---|---:|---|---|
+| ZAIP-AIOS | **95** | Lidera tecnicamente neste recorte local ao unir SDD, arquitetura limpa e qualidade baseada em Evidence com orquestração multiagente, segurança, contexto e observabilidade financeira por Task no mesmo lifecycle auditável. | Plataforma completa para engenharia de software com agentes, reunindo especificação, execução, validação, segurança e observabilidade em um lifecycle rastreável. |
+| Traycer | 83 | Coding agents conectados, loops agente–agente para arquitetura/review, CLI/terminal e worktrees são fortes; custo por Task e execução do host assinado não foram reproduzidos. | Mais especializado que OpenClaw para orquestrar coding agents, sem substituir validação de produto. |
+| AIOX Core | 82 | Spec pipeline, dev/QA, worktrees, recovery, memória e integrações Codex/Cursor/Claude sustentam o fluxo; hooks têm paridade desigual e não há custo por Task. | Plataforma de desenvolvimento ampla, com DX forte mas menos direta que Traycer. |
+| Kilo Code | 80 | Agente de código para VS Code, JetBrains e CLI, com Debug, Review, autocorreção e \`kilo run --auto\`; telemetria existe, mas custo por Task não foi comprovado. | DX de programação first-class, com limites de evidência em isolamento e recovery. |
+| TLC Spec-Driven | 80 | Skill SDD adaptativo com AC→teste, matriz de cobertura, verifier independente, sensor de discriminação e lessons locais; o contrato é forte, mas o enforcement depende de agente/host. | Muito forte em rastreabilidade e verificação; benchmark autorreferenciado sem bruto e sem telemetria/custo por Task. |
+| Roo Code | 79 | VS Code com modos Code, Architect e Debug, refactor, histórico/resume e worktrees; não há custo consolidado por Task. | Encaixe editor-first muito forte, com governança operacional parcial. |
+| Superpowers | 78 | Skills de TDD, worktrees, subagentes, review e debugging tornam o playbook de programação consistente; suas garantias continuam instrucionais e os testes comportamentais dependem de repositório externo. | Forte disciplina para coding agents, sem lifecycle tipado nem custo por Task. |
+| OpenClaw | 73 | Subagentes Codex-native, sessões isoladas, sandbox e testes são fortes, mas o gateway assistente multicanal não demonstra o mesmo fluxo coding-first de IDE/CLI. | Referência em isolamento e operação geral; fica abaixo de Traycer, Kilo e Roo no recorte de programação. |
+| Hermes | 71 | Retry, memória e usage/pricing sustentam recursos de coding, mas a plataforma é generalista e não coding-first; custo por Task não está demonstrado. | Produto autônomo amplo, não equivalente automaticamente a um agente de desenvolvimento especializado. |
+| OpenSpec | 70 | Delta specs, schemas, CLI, workspaces e testes estruturam a evolução de mudanças; a verificação é opcional/parcialmente heurística. | Especialista em gestão de specs, não runtime multiagente, sem custo por Task. |
+| OpenCode  | 60 | TUI/CLI, edição/patch, comandos, LSP, MCP/providers, permissões e sessões SQLite compõem uma base enxuta e extensível para programação no terminal. | Alternativa direta para desenvolvimento no terminal, com oportunidades de ampliar multiagentes, lifecycle, testes e custo por Task. |
+
+**Consultar a matriz técnica dos dez critérios**
+
+| Tópico (0–10) | ZAIP | OpenClaw | Traycer | Kilo | Hermes | AIOX | Roo Code | OpenCode | TLC Spec-Driven | Superpowers | OpenSpec |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| T1 — SDD e rastreabilidade | 10 | 6 | 7 | 6 | 6 | 9 | 6 | 3 | 9 | 8 | 9 |
+| T2 — Loop planejar–editar–testar–corrigir | 9 | 7 | 9 | 10 | 7 | 9 | 9 | 8 | 9 | 9 | 6 |
+| T3 — Multiagentes e isolamento | 10 | 9 | 9 | 8 | 7 | 9 | 8 | 4 | 8 | 9 | 5 |
+| T4 — Arquitetura e repositório | 10 | 8 | 9 | 8 | 7 | 8 | 8 | 8 | 7 | 7 | 8 |
+| T5 — Testes, review e evidência | 10 | 9 | 9 | 9 | 8 | 9 | 9 | 5 | 9 | 9 | 8 |
+| T6 — Recovery e idempotência | 10 | 7 | 9 | 7 | 7 | 8 | 7 | 6 | 8 | 8 | 7 |
+| T7 — Supply chain | 9 | 8 | 8 | 8 | 8 | 7 | 8 | 6 | 7 | 7 | 6 |
+| T8 — Memória de codebase | 9 | 8 | 9 | 8 | 9 | 9 | 8 | 7 | 9 | 8 | 8 |
+| T9 — Telemetria/custo por tarefa de programação | 9 | 6 | 5 | 6 | 6 | 6 | 6 | 4 | 5 | 4 | 4 |
+| T10 — DX CLI/IDE, debug, review, setup e Codex-first | 9 | 5 | 9 | 10 | 6 | 8 | 10 | 9 | 9 | 9 | 9 |
+
+
+## Da conversa ao trabalho executável
+
+O framework ZAIP-AIOS transforma linguagem natural em engenharia estruturada. O usuário pode enviar uma mensagem curta, manter uma conversa de refinamento ou fornecer a transcrição de um áudio longo explicando contexto, restrições e resultado desejado. O framework avalia complexidade, dependências, amplitude e risco para propor a entrada adequada: uma Task para trabalho direto, uma SPEC para uma entrega técnica com múltiplas Tasks ou um PRD para uma iniciativa de produto composta por uma ou mais SPECs. A criticidade \`leve\`, \`padrão\` ou \`crítica\` determina a profundidade de planejamento, revisão, segurança e evidência exigida; nenhum artefato fica fechado à revisão humana.
+
+Isso permite sair de uma conversa livre sem cair em *vibe coding*: perguntas e análises read-only permanecem Conversations sem Task; pedidos de ação tornam-se trabalho executável. Antes da mutação, a intenção é convertida em requisitos, critérios de aceite, escopo, dependências e write scopes, e uma Task com Run raiz de orquestração entra em Execução. Consulte [Lifecycle de Conversations, Tasks, SPECs e PRDs](.agents/zaip-aios/guides/28-lifecycle-completo.md).
+
+## Método ZAIP em seis etapas
+
+| Etapa | Artefatos | O que acontece |
+| --- | --- | --- |
+| **1. Definição** | PRD + Requirements | Registra objetivo, contexto, público, restrições, resultado esperado e Critérios de Aceite que definem o trabalho. |
+| **2. Planejamento** | SPEC + Changes | Descreve escopo, solução, arquitetura, riscos e mudanças previstas antes da execução, seguindo SDD. |
+| **3. Execução** | Tasks + DAG + Executions + Runs | Coordena Tasks, dependências, agentes e arquivos produzidos; registra cada tentativa e seu consumo observável. |
+| **4. Decisões** | Decisions (Human + AI / Planning + Execution) | Preserva decisões humanas e da IA tomadas durante planejamento, execução, revisão e reparo, com contexto e consequências. |
+| **5. Verificação** | Tests + Reviews + Evals + Checks | Executa os mecanismos de qualidade e compara o resultado observado com os requisitos e Critérios de Aceite. |
+| **6. Evidências** | Evidence + Results + Traceability | Coleta, registra e relaciona as provas produzidas pela verificação às Tasks, Changes, Runs e aos Critérios de Aceite; o trabalho só é concluído quando as evidências são suficientes e reproduzíveis. |
+
+O método mantém intenção e execução separadas. PRD e SPEC explicam o que se pretende entregar; Change, Task, Execution e Run registram como o trabalho foi realizado; Decisions explicam por que caminhos relevantes foram escolhidos; a Verificação executa testes, reviews, evals e checks; e Evidence preserva os resultados observados e sua relação com os Critérios de Aceite. Assim, “concluído” é um estado demonstrado por diff, resultado e evidência reproduzível, não apenas declarado por um agente.
+
+## Cadeia completa de execução
+
+Os conceitos abaixo formam o vocabulário técnico usado para ligar intenção, planejamento, execução e prova sem perder o histórico.
+
+**Consultar o glossário completo do lifecycle**
+
+| Conceito | Responsabilidade |
+| --- | --- |
+| **Rule** | Regra durável de comportamento, arquitetura, segurança, contexto ou qualidade que o Codex deve seguir. |
+| **Requirement** | Obrigação verificável do produto, acompanhada de Critérios de Aceite. |
+| **PRD** | Documento de Requisitos do Produto que governa uma iniciativa e organiza uma ou mais SPECs. |
+| **SPEC** | Especificação técnica SDD que detalha solução, escopo, riscos, Changes, Tasks e DAG. |
+| **Change** | Narrativa viva de uma mudança planejada e executada: decisões, arquivos afetados, desvios, testes, evidências, rollout, rollback e resultado. |
+| **Task** | Menor unidade executável, com objetivo, risco, prioridade, dependências, write scopes e critérios de aceite. |
+| **DAG** | Grafo acíclico que ordena dependências, identifica paralelismo seguro e impede execução fora da sequência necessária. |
+| **Execution** | Unidade de interação ou entrega, correlacionada ao turno observável: \`interaction\` registra conversa/definição; \`delivery\` coordena trabalho materializado. A idempotência depende da identidade observada do turno; continuação pode reutilizar a delivery vigente. |
+| **Run / Sub-Run** | Run de captura ou do agente orquestrador possui \`parent_run_id: null\`; Sub-Run é cada chamada de subagente relacionada por \`parent_run_id\`. Novos registros usam \`run_role: intake|orchestrator|subagent\`; cada chamada fixa modelo e effort e agrega suas Calls internas. |
+| **Decision** | Decisão humana ou da IA com contexto, alternativa escolhida, motivo, consequências e possibilidade de rollback. |
+| **Evidence** | Prova associada à Task e aos Critérios de Aceite: teste, diff, review, check, relatório ou resultado reproduzível. |
+| **Eval** | Avaliação determinística ou orientada por rubrica que mede qualidade, regressão, aderência e performance. |
+
+
+## Três formas de executar
+
+1. **Task-first:** executa uma única Task independente para mudanças diretas e bem delimitadas.
+2. **SPEC:** executa um conjunto de Tasks relacionadas, coordenadas por uma DAG e governadas pela mesma especificação técnica.
+3. **PRD:** executa uma iniciativa completa, selecionando uma ou mais SPECs, cada uma com suas Changes, Tasks e dependências.
+
+Essa progressão permite começar de forma simples e acrescentar planejamento apenas quando a amplitude, as dependências ou o risco justificarem uma estrutura maior.
+
+**Políticas técnicas de execução e assurance**
+
+Conversation e Task-first preservam a seleção manual do host; o default do projeto não é aplicado automaticamente a uma Task avulsa. A política automática aceita origens SPEC/PRD configuradas em \`automatic_sources\`, com velocidade \`standard\`. Modelo e effort ficam fixos em cada Run/Sub-Run; capacidade ou velocidade indisponível no host não pode ser presumida pelo ZAIP. Consulte a [política de modelos](.agents/zaip-aios/guides/23-orquestracao-de-modelos.md).
+
+O intake correlaciona o turno observável à Execution. \`prepare\` valida o plano, sem autorizar implementação; \`ready\` materializa trabalho preparado e \`execute\` inicia a entrega autorizada. Toda delivery e interaction com descendentes exigem executor elegível e \`zaip-agent-finalizer\` por último. Interaction read-only sem descendentes termina após a resposta, sem esse circuito. Publicação puramente Git é uma exceção: não materializa lifecycle. SPEC/PRD permanecem ativos entre Runs filhas e só são entregues por gates parentais.
+
+A profundidade de prova é adaptativa: Task standalone \`lite\` exige no mínimo uma validação tipada e uma Evidence, normalmente uma de cada, mas aceita provas adicionais legítimas. \`standard\` exige duas ou três validações conforme \`verification_scope\` e pelo menos uma Evidence consolidada; \`critical\` exige três ou mais, revisão independente e os sinais de risco persistidos que determinam controles adicionais. Entregas de SPEC e PRD acrescentam matriz parental, pelo menos três validações e três Evidences, integração real e revisão independente. O runtime manual continua padrão; a autonomia por Codex ou Claude é opt-in, isolada em worktrees e limitada por write scopes, commits, budgets e gates tipados. Consulte [Assurance adaptativa e autonomia opt-in](.agents/zaip-aios/guides/19-assurance-e-autonomia.md).
+
+
+## Princípios de engenharia autônoma
+
+O ZAIP-AIOS combina velocidade com limites explícitos. Seus princípios mantêm o código sustentável, distribuem apenas o contexto necessário e exigem comprovação proporcional ao risco.
+
+O padrão do schema é \`execution.runtime: manual\` quando a opção está ausente; este checkout optou por \`autonomous\` em \`project.yaml\`. A configuração não dispensa pedido de execução nem autoriza publicar. Consulte sempre o arquivo efetivo do projeto, não apenas o default descrito no guia.
+
+- **Clean Architecture:** domínio, aplicação, adapters e infraestrutura permanecem separados; regras de negócio não dependem de frameworks ou detalhes externos, as dependências apontam para as camadas internas e composition roots conectam implementações concretas nas bordas.
+- **CQRS:** commands e queries seguem fluxos explícitos e independentes; comandos alteram estado por casos de uso e ports apropriados, enquanto consultas não produzem efeitos colaterais e retornam read models adequados à leitura.
+- **Modularização e organização do código:** pastas, arquivos, módulos e componentes são estruturados por domínio e responsabilidade, com fronteiras explícitas, alta coesão e baixo acoplamento para facilitar navegação, manutenção, testes e evolução do software.
+- **Autonomia dentro de limites:** subagentes trabalham com DAG, write scopes, sandbox, approvals, budgets, regras de segurança e gates proporcionais ao risco.
+- **Contexto progressivo:** cada agente recebe apenas Rules, Requirements, skills e evidências relevantes para seu papel, reduzindo ruído, custo e perda de contexto.
+- **Conclusão baseada em prova:** testes, review, evals, checks e Evidence precisam cobrir os Critérios de Aceite antes da entrega.
+- **Histórico recuperável:** decisões, mudanças, tentativas, falhas, retries, reparos e rollback permanecem vinculados, permitindo pausar, retomar e auditar o trabalho.
+- **Observabilidade honesta:** tokens, custo, tempo, cobertura e performance são medidos por escopo; ausência de telemetria permanece explícita em vez de gerar precisão fictícia.
+
+O intake captura uma vez por turno observável e reutiliza o foco válido em continuações; publicação puramente Git não cria lifecycle. Perguntas, feedbacks e análises read-only usam Execution \`interaction\`, sem Task ou Change artificial. A criação/refino explícito de PRD/SPEC \`draft\` pode persistir esses macros e o PreparedPlan em interaction, sem delivery. Fora dessa exceção, uma edição avulsa independente materializa e inicia Task, Change, delivery e Run antes da primeira mutação; preparação explicitamente solicitada pode parar em Pronto para Executar. PRD \`draft\` ocupa Definição e SPEC \`draft\` ocupa Planejamento; Tasks nunca ocupam essas colunas.
+
+## Graph Engineering e Loop Engineering
+
+<img src=".agents/config/src/zaip-aios-obsidian.png" alt="Zaip AIOS no Obsidian" width="100%">
+
+O **Graph Engineering** transforma uma entrega complexa em uma sequência coordenada de responsabilidades. Em vez de acionar todos os 23 agentes, a orquestração escolhe o menor conjunto capaz de planejar, executar, revisar e comprovar o resultado conforme dependências, risco e especialidade.
+
+Essa autonomia permanece governada: Dave coordena, cada executor recebe apenas o escopo necessário, Nanda realiza a revisão independente, especialistas adicionais entram quando existem sinais objetivos e Gui encerra o fluxo por último. O resultado é uma equipe ajustada à demanda, sem multiplicar agentes e custo sem necessidade.
+
+O **Loop Engineering** orienta o que acontece quando a primeira tentativa não satisfaz os critérios de qualidade. A falha ou o bloqueio é classificado, o próximo ciclo recebe uma configuração proporcional à dificuldade observada e cada tentativa permanece auditável. Em execuções originadas de PRD ou SPEC, o sistema pode evoluir de **Luna → Terra → Sol** e de **low → medium → high → xhigh**; Conversations e Tasks avulsas preservam a seleção manual do host/Codex. O modelo nunca muda silenciosamente dentro da mesma Run.
+
+### Fluxo resumido
+
+Um fluxo de entrega com revisão independente é **entrada → Dave → executor por capacidade → Nanda (review) → Gui (finalização)**. A revisão deve atender ao perfil de assurance; não é obrigatório expandir todo trabalho para o mesmo conjunto de agentes. Todos os filhos são coordenados pela orquestração; a sequência não significa que um trabalhador chama o próximo.
+
+Os cenários completos ficam no [guia de fluxos e roteamento](.agents/zaip-aios/guides/22-fluxos-e-roteamento.md), em texto estável para o GitHub.
+
+### Fluxos resumidos
+
+O lifecycle segue **Definição → Planejamento → Pronto para Executar → Execução → Verificação → Concluído**. Bloqueado, Falhado e Cancelado são saídas alternativas.
+
+Task, SPEC e PRD mantêm fluxos independentes; Conversation usa uma Execution interaction e não cria Task artificial. A Task direta inicia imediatamente, enquanto a preparada aguarda execute.
+
+![Lifecycles de Task, SPEC e PRD](.agents/zaip-aios/guides/assets/diagrams/lifecycles-task-spec-prd.png)
+
+Os fluxos detalhados de roteamento, entrada, planejamento, rework, demanda crítica, seleção de modelo, os 23 agentes e orquestração de Task estão no [guia de fluxos e roteamento](.agents/zaip-aios/guides/22-fluxos-e-roteamento.md).
+
+## Referência técnica e operacional
+
+As seções seguintes preservam os contratos necessários para instalação avançada, manutenção, auditoria, segurança e evolução do framework. Elas complementam a visão comercial sem substituir os guias especializados vinculados ao longo do documento.
+
+## Estrutura atual de \`.agents\`
+
+**Consultar a árvore de diretórios e as responsabilidades técnicas**
+
+\`\`\`text
+.agents/
+├── config/
+│   ├── project.yaml
+│   ├── framework.lock.yaml
+│   ├── agents/catalog.yaml
+│   └── profiles/clients.yaml
+├── dashboard/
+│   ├── zaip-dashboard-windows.exe
+│   ├── zaip-dashboard-linux.sh
+│   ├── zaip-dashboard-mac.command
+│   ├── apps/frontend/
+│   ├── modules/{operations,cost-monitor,traceability}/
+│   ├── packages/
+│   └── tests/e2e/
+├── design/
+│   ├── DESIGN.md
+│   ├── tokens.json
+│   ├── zaip-design.exe
+│   ├── apps/catalog/
+│   └── packages/
+├── branding/                         # artefatos de negócio, criada sob demanda
+├── marketing/                        # artefatos de negócio, criada sob demanda
+├── sales/                            # artefatos de negócio, criada sob demanda
+├── growth/                           # artefatos de negócio, criada sob demanda
+├── records/
+│   ├── prds/<ano>/<mês>/
+│   ├── specs/<ano>/<mês>/
+│   ├── changes/<ano>/<mês>/
+│   ├── tasks/<ano>/<mês>/
+│   ├── executions/<ano>/<mês>/
+│   ├── runs/<ano>/<mês>/
+│   ├── lifecycle/                    # manifests, índices e projeções
+│   └── telemetry/<ano>/<mês>/writers/<writer-id>/{manifest.json,chunks/}
+├── rules/
+│   ├── core.md
+│   ├── workflow.md
+│   └── *.md                          # Rules gerenciadas e locais, layout plano
+├── requirements/
+├── skills/
+├── tools/
+│   ├── catalog.yaml
+│   ├── {mcp,api}/
+│   ├── policies/
+│   ├── profiles/
+│   ├── runtime/
+│   └── servers/
+├── zaip-aios/
+│   ├── INDEX.md
+│   └── guides/
+├── runtime/
+│   └── bin/zaip.mjs                  # CLI instalado e metadados de distribuição
+├── .env.example
+└── .gitignore
+.local/                              # na raiz do workspace; ignorado pelo Git
+├── claims/                          # claims atômicos de lifecycle
+├── codex-telemetry-spool/v1/          # captura sanitizada, privada e recuperável
+└── dashboard-sqlite/                 # read model descartável
+\`\`\`
+
+As pastas \`branding/\`, \`marketing/\`, \`sales/\` e \`growth/\` são áreas de artefatos de negócio criadas sob demanda. A existência e o conteúdo variam por projeto; não é necessário criar pastas vazias.
+
+| Caminho | Responsabilidade |
+| --- | --- |
+| \`config/\` | Configuração do projeto, perfis de clientes e agentes, maturidade de capacidades e lock de integridade dos arquivos gerenciados. |
+| \`dashboard/\` | Dashboard operacional local com Kanban, custos, tempo, tokens e rastreabilidade; consulta projeções reconstruíveis dos registros canônicos, incluindo SQLite. |
+| \`design/\` | Design system do ZAIP, tokens visuais, catálogo de componentes e launcher local de inspeção. |
+| \`branding/\` | Artefatos de negócio de branding, como Brandbook, plataforma de marca e governança de identidade; é criada sob demanda. |
+| \`marketing/\` | Artefatos de negócio de estratégia, campanhas, conteúdo e ativos de marketing; é criada sob demanda. |
+| \`sales/\` | Artefatos de negócio de metodologia comercial, qualificação, playbooks, scripts e handoffs; é criada sob demanda. |
+| \`growth/\` | Artefatos de negócio de estratégia de crescimento, RevOps e experimentos; é criada sob demanda. |
+| \`records/\` | Fonte canônica Git-native de PRDs, SPECs, Changes, Tasks, Executions e Runs. \`records/lifecycle\` contém manifests, índices, chunks e resumos para descoberta e paginação sem varrer o histórico. |
+| \`requirements/\` | Requisitos duráveis e Critérios de Aceite de lifecycle, execução, custos, contexto, dashboard, arquitetura e design system. |
+| \`rules/\` | Rules canônicas do framework e Rules locais do projeto, todas diretamente neste diretório. |
+| \`skills/\` | Workflows reutilizáveis que transformam conversas em Requirements, Tasks, SPECs e PRDs e orientam execução, revisão, segurança, custos, contexto e ferramentas. |
+| \`tools/\` | Catálogo de MCPs e APIs, políticas de aprovação e segredos, perfis de ativação, doctors e servidores locais gerados de maneira auditável. |
+| \`zaip-aios/\` | Handbook operacional com índice de baixo custo de contexto e guias de instalação, execução, revisão, agentes, custos, segurança e integração com Codex. |
+| \`../.local/\` | Diretório na raiz do workspace com claims, writer ID, spool sanitizado e SQLite descartável; fica fora do Git. O Dashboard consulta a projeção, mas os registros canônicos permanecem em \`records/\`. |
+
+\`framework.lock.yaml\` é a referência mecânica dos arquivos administrados pela distribuição, enquanto \`project.yaml\` descreve o projeto consumidor. Rules presentes no lock pertencem ao framework e podem ser atualizadas pelo setup; Rules ausentes do lock são locais e devem ser preservadas. O agente começa por \`rules/core.md\`, usa os manifests canônicos em \`records/lifecycle\` para descoberta e só abre um registro histórico quando já possui seu ID explícito.
+
+O código canônico do Dashboard vive em \`.agents/dashboard\`, separado das aplicações do produto. Ele possui somente \`apps/frontend\`; o servidor loopback está em \`packages/local-runtime\`, não em \`apps/backend\`. Os módulos \`operations\`, \`cost-monitor\` e \`traceability\` consomem read models derivados, com consultas SQLite no runtime atual e caminhos de compatibilidade em memória. A API é predominantemente de leitura, com endpoints controlados para ações como configuração, prioridade, refresh e reconciliação explícita; isso não é permissão para alterações arbitrárias. Os launchers Windows, Linux e macOS ficam diretamente em \`.agents/dashboard\`; sua presença no template não comprova execução nos três ambientes.
+
+
+## Arquitetura das aplicações
+
+**Consultar layout, dependências e limites de código**
+
+Quando essas superfícies existirem, a estrutura canônica é:
+
+\`\`\`text
+apps/
+├── frontend/       # UI do produto e composition root do cliente
+├── backend/        # APIs, workers e composition roots de servidor
+└── site/           # landing page e site público, implantável separadamente
+modules/<area>/     # capacidades de negócio e seus contratos públicos
+packages/<library>/ # bibliotecas técnicas reutilizáveis
+tests/e2e/          # fluxos que atravessam aplicações
+\`\`\`
+
+A direção de dependência é \`apps -> modules -> packages\`. Esta arquitetura descreve exclusivamente o código das aplicações do produto consumidor, não o dashboard ZAIP nem os domínios de negócio. As áreas \`branding/\`, \`marketing/\`, \`sales/\` e \`growth/\` ficam em \`.agents\` como pastas de artefatos de negócio criadas sob demanda; elas não são pastas de aplicação. \`apps/site\` nunca importa o dashboard, não lê \`.agents\` e não depende de implementação privada do backend. Pastas de superfícies ausentes não precisam ser criadas vazias. Testes unitários ficam junto do código; jornadas cross-app ficam em \`tests/e2e\`.
+
+Arquivos-fonte com 401–800 linhas geram warning e arquivos com 801 ou mais linhas geram erro, salvo exceções explícitas. O gate ignora código gerado, distribuição, vendor, dados e lockfiles. A lista em [source-size-baseline.json](scripts/source-size-baseline.json) inclui legado de pacotes e Dashboard, com limite congelado, responsável, motivo e validade; isso não autoriza aumentar os limites para ocultar crescimento.
+
+
+## Desenvolvimento do framework
+
+**Consultar contratos para mantenedores e contribuidores**
+
+Esta seção é destinada a mantenedores e contribuidores que alteram o código-fonte do próprio ZAIP-AIOS. Quem apenas instalou o framework dentro de outro repositório não precisa executar esta rotina para usar o Codex, criar Tasks, SPECs ou PRDs, acompanhar o dashboard ou executar o lifecycle normalmente.
+
+### Repositório-fonte e projeto consumidor
+
+- **Repositório-fonte:** contém a implementação oficial do ZAIP-AIOS, seus pacotes, dashboard, Rules, Requirements, skills, ferramentas e artefatos de distribuição. Mudanças intencionais nesses componentes precisam passar pelos gates de integridade, qualidade, testes e build.
+- **Projeto consumidor:** recebe uma versão publicada do framework dentro de \`.agents\`. O arquivo \`framework.lock.yaml\` é atualizado somente pelos fluxos transacionais de instalação ou upgrade do CLI; o projeto consumidor não executa \`sync:framework-lock\` para aceitar alterações locais.
+
+Configurações do projeto consumidor permanecem em \`.agents/config/project.yaml\`; Rules adicionais ficam diretamente em \`.agents/rules/*.md\` e não entram no lock do framework. Arquivos administrados pela distribuição não devem ser modificados e depois incorporados ao lock apenas para silenciar uma divergência.
+
+### Integridade dos arquivos gerenciados
+
+O \`framework.lock.yaml\` é um manifesto mecânico de integridade, não um lock de dependências como \`pnpm-lock.yaml\`. Ele registra os caminhos e hashes SHA-256 dos arquivos que pertencem à distribuição do ZAIP-AIOS, permitindo detectar alteração acidental, arquivo ausente ou conteúdo diferente do release esperado. Ele não armazena segredos, telemetria ou histórico de execução.
+
+Quando um mantenedor altera intencionalmente Rules, Requirements, skills ou outro arquivo gerenciado no repositório-fonte, deve revisar a mudança e então regenerar os hashes:
+
+\`\`\`bash
+pnpm sync:framework-lock
+pnpm validate:framework-lock
+\`\`\`
+
+\`sync:framework-lock\` grava o novo conjunto de caminhos e hashes no lock. \`validate:framework-lock\` é somente leitura: recalcula o estado esperado e falha se houver drift. O sync não deve ser usado automaticamente para esconder uma divergência; primeiro é necessário confirmar que a mudança pertence de fato ao framework e deve fazer parte da próxima distribuição.
+
+### Gates locais de qualidade
+
+| Comando | O que verifica |
+| --- | --- |
+| \`pnpm validate:framework-lock\` | Confirma que todos os arquivos gerenciados correspondem aos caminhos e hashes registrados no lock. |
+| \`pnpm validate:skills\` | Valida estrutura, nomes, frontmatter, interfaces, links, recursos e invariantes de segurança das skills. |
+| \`pnpm test:encoding\` | Detecta UTF-8 inválido, caracteres corrompidos, *mojibake* e outros problemas de codificação textual. |
+| \`pnpm validate:source-size\` | Mede arquivos de código, aplica limites e exceções temporárias e sinaliza componentes que precisam ser divididos em módulos mais coesos. |
+| \`pnpm lint\` | Verifica formatação, consistência e regras estáticas do código. |
+| \`pnpm typecheck\` | Executa a validação de tipos TypeScript nos pacotes do workspace. |
+| \`pnpm test\` | Executa os testes automatizados dos pacotes por meio do workspace. |
+| \`pnpm build\` | Compila e empacota os componentes, além de normalizar os textos gerados. |
+
+Uma validação local típica, depois de atualizar o lock quando necessário, é:
+
+\`\`\`bash
+pnpm validate:framework-lock
+pnpm validate:skills
+pnpm test:encoding
+pnpm validate:source-size
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+\`\`\`
+
+Antes de integrar uma mudança relevante ou preparar um release, \`pnpm verify\` executa a pipeline completa do repositório, incluindo gates adicionais de ferramentas, contratos, geração, workspace, paridade de runtime e testes de release. Essa pipeline apenas valida o lock; se um arquivo gerenciado tiver sido alterado intencionalmente, o sync deve acontecer antes.
+
+Use a versão de pnpm fixada em \`packageManager\` (\`corepack pnpm\` quando disponível). Para uma alteração delimitada, selecione os checks pertinentes ao risco e ao diff; a lista acima não exige repetir todos os testes a cada edição documental. Qualificação de release usa os gates completos do [guia 26](.agents/zaip-aios/guides/26-qualidade-e-release.md) no candidato exato. Não confunda \`validate:github:prepared\`, execução local, push e CI terminal verde.
+
+A arquitetura detalhada está resumida na seção [Arquitetura das aplicações](#arquitetura-das-aplicações) deste README.
+
+
+## Segurança com perfis de permissão
+
+O ZAIP-AIOS oferece dois perfis de permissão para equilibrar conveniência e contenção. O perfil selecionado por \`default_permissions\` define o limite técnico que o processo pode alcançar, enquanto instruções, Rules, hooks e skills continuam determinando o que o agente está autorizado a fazer.
+
+| Perfil | Filesystem nativo no Windows | Rede de comandos | Quando usar |
+| --- | --- | --- | --- |
+| \`zaip-aios-full-access\` | Escrita em \`C:\\\` inteiro, sujeita às ACLs e aos privilégios da conta Windows | Completa, com todos os domínios permitidos | Padrão humano; ainda exige autorização explícita para ações externas, destrutivas, publicação e elevação. |
+| \`zaip-aios-security\` | Escrita somente na raiz física deste repositório e seus descendentes, incluindo \`.git\`, \`.agents\` e \`.codex\`; escrita em \`~/.ssh\` apenas para fluxos Git/SSH autorizados | Limitada a \`github.com\` | Opt-in para menor privilégio; reinicie o Codex depois de selecioná-lo. |
+
+**Consultar funcionamento, riscos e defesa em profundidade**
+
+O perfil restrito usa uma tabela de permissões com a **raiz física absoluta** do repositório,
+não \`:workspace\` nem \`:workspace_roots\`. Essa escolha mantém \`.agents\`, \`.codex\` e \`.git\`
+editáveis no Windows sem liberar o restante de \`C:\\\`. Seu \`approval_policy = "never"\` não
+autoriza ações por si só: deploy, publicação, mutações remotas e ações destrutivas continuam
+dependendo de pedido explícito, instruções, Rules, hooks e skills.
+
+### Risco do \`zaip-aios-full-access\`
+
+\`zaip-aios-full-access\` é um perfil de maior risco. Ele pode alcançar outros repositórios,
+arquivos do usuário, diretórios de aplicações e do sistema, além de qualquer destino de rede que
+o host permita. Um comando incorreto, conteúdo externo malicioso ou uma dependência comprometida
+tem, portanto, impacto potencial muito maior. O perfil não concede privilégios de administrador e
+ainda respeita ACLs, políticas corporativas e arquivos em uso, mas essas barreiras não tornam o
+acesso equivalente ao perfil restrito.
+
+\`zaip-aios-full-access\` é o padrão humano e deve ser usado somente dentro da autoridade explícita
+do pedido. Quando uma operação puder ser executada com contenção de workspace, o usuário pode
+selecionar \`zaip-aios-security\` e reiniciar completamente o Codex para que o sandbox materialize o
+perfil escolhido. Não altere perfis apenas para contornar uma negação de permissão.
+
+### Defesa em profundidade
+
+Os dois perfis mantêm camadas compensatórias que reduzem risco, mas elas não substituem o
+isolamento nativo oferecido pelo perfil restrito:
+
+- carregamento da política somente em repositório confiável e escopo explícito em \`AGENTS.md\`;
+- hook \`PreToolUse\`, com verificações para classes conhecidas de escapes, referências a segredos, Git destrutivo, force push, mutações de OS, ACL, persistência, elevação e banco destrutivo, quando o host efetivamente o executa;
+- regras Codex \`forbidden\`, instruções e skills que exigem autoridade explícita e limitam o escopo de cada operação;
+- deploy GitHub delimitado por pedido explícito, preflight, branch/remoto definidos e identidade SSH escopada;
+- proteção para que tokens, chaves privadas, credenciais e valores de ambiente não sejam impressos, registrados ou incluídos em commits;
+- Tasks, Changes, Executions, Runs, write scopes, threat model, rollback, testes negativos e review independente proporcionais ao risco;
+- subagentes com responsabilidades e escopos delimitados, além de adapters com hash, framework lock e gates de regressão;
+- controles remanescentes do sistema operacional, como ACLs, privilégios da conta e políticas do host.
+
+O hook de segurança \`PreToolUse\` também permanece ativo no perfil full-access, sem reduzir suas permissões nativas; ele bloqueia classes destrutivas, segredos, publicação e elevação sem autorização. Os hooks de lifecycle de subagentes permanecem ativos como
+defesa em profundidade e para atribuição/telemetria. Browser, Computer Use, MCPs e demais
+integrações têm superfícies próprias e devem ser habilitados e usados apenas quando necessários.
+Para isolamento forte contra erros de escopo ou código malicioso, use o perfil restrito e, quando
+o risco justificar, uma conta, VM ou controles externos de rede e filesystem dedicados.
+
+O modelo de ameaça, a matriz allow/deny, todas as camadas, limitações, operação segura,
+rollout, rollback e comandos de verificação estão documentados no
+[guia completo de segurança dos perfis ZAIP-AIOS](.agents/zaip-aios/guides/10-seguranca.md).
+
+
+## Automação e integrações opcionais
+
+### Agendamento horário da fila pronta
+
+No Codex Desktop, o agendamento horário da fila pronta é configurado pela skill \`$zaip-skill-instalar-agendamento\` em uma única conversa no checkout local. A skill usa a automação nativa de tarefas agendadas para criar ou atualizar uma tarefa standalone com nome estável; ela não duplica registros e falha fechada se a capacidade \`automation_update\` não estiver disponível. A tarefa agendada chama explicitamente \`$zaip-skill-executar-fila-pronta\` em cada rodada horária.
+
+A rodada processa sequencialmente todo o snapshot elegível: primeiro PRDs em \`ready\`, depois SPECs \`ready\` independentes e, por último, Tasks avulsas materializadas em **Pronto para Executar**. Itens descendentes, ativos, bloqueados, falhos ou terminais ficam fora. Em **Dashboard > Trabalho (Kanban) > Pronto para Executar**, a prioridade é definida pela numeração de cima para baixo dentro do tier PRD/SPEC/Task e persiste para o scheduler em \`.agents/dashboard/work-priority.json\`; os controles acessíveis de ordenação atualizam essa numeração, e itens sem número vão para o fim pelo fallback determinístico. Um lock/lease local evita sobreposição entre rodadas.
+
+O repositório versiona esse contrato, mas não instala um relógio em cada clone. A tarefa agendada pertence à máquina/usuário que a criou e depende da máquina ligada, do Codex Desktop em execução e da automação nativa disponível; sem eles, a skill falha fechada e não promete execução futura.
+
+### Codex, documentação oficial e navegador
+
+O arquivo \`.codex/config.toml\` é uma configuração de projeto carregada pelo Codex somente quando o repositório é confiável. Na configuração atual do ZAIP-AIOS, ele orienta a descoberta de \`AGENTS.md\` e habilita o MCP oficial e read-only da documentação OpenAI, permitindo que o agente consulte informações atuais sobre Codex, modelos, APIs, SDKs e MCP sem depender apenas da memória do modelo. O instalador também disponibiliza a skill ZAIP de descoberta, enquanto o próprio Codex fornece recursos estáveis como shell, subagentes, apps, hooks e busca web conforme a superfície, a conta e as políticas do ambiente.
+
+A configuração deste checkout contém entradas habilitadas para plugins de navegador; isso não comprova instalação, disponibilidade nem permissão efetiva no host. Quando o Browser do app estiver disponível, ele pode apoiar navegação, interação e captura real da aplicação, sujeito às permissões e confirmações de ações sensíveis. Não presuma a mesma ferramenta em outra superfície Codex. Para Playwright ou outro MCP, consulte o manifesto e a política em \`.agents/tools\` antes de ativar uma implementação. Falha de captura deve ser registrada como pendência de prova, nunca como validação visual aprovada.
+
+## Visualização opcional da rastreabilidade no Obsidian
+
+A skill \`criar-pasta-obsidian\` gera em \`.local/obsidian/vault\` uma projeção local e reconstruível das relações entre PRDs, SPECs, Changes, Tasks, Executions, Runs, requisitos, evidências e testes. Ela não transforma o Obsidian em fonte de verdade, não duplica os corpos completos dos registros e não exige que o aplicativo esteja instalado para gerar ou validar a pasta.
+
+Na raiz do repositório, a geração ou atualização do vault utiliza:
+
+\`\`\`powershell
+node .agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.mjs
+\`\`\`
+
+O [guia de Obsidian para rastreabilidade ZAIP](guide/CRIAR-PASTA-OBSIDIAN.md) documenta a instalação do aplicativo, a abertura da pasta como vault, a geração de uma única Task e a atualização da projeção após um \`git pull\`.
+`,N=t(),P=Object.assign({"../../../../zaip-aios/guides/01-primeiros-passos.md":r,"../../../../zaip-aios/guides/02-requirements.md":i,"../../../../zaip-aios/guides/03-tasks.md":a,"../../../../zaip-aios/guides/04-specs.md":o,"../../../../zaip-aios/guides/05-prds.md":s,"../../../../zaip-aios/guides/06-execucao.md":c,"../../../../zaip-aios/guides/07-revisao-e-validacao.md":l,"../../../../zaip-aios/guides/08-contexto-e-tokens.md":u,"../../../../zaip-aios/guides/09-agentes-e-squads.md":d,"../../../../zaip-aios/guides/10-seguranca.md":f,"../../../../zaip-aios/guides/11-observabilidade-e-custos.md":p,"../../../../zaip-aios/guides/12-instalacao-e-upgrade.md":m,"../../../../zaip-aios/guides/13-boas-praticas.md":h,"../../../../zaip-aios/guides/14-troubleshooting.md":g,"../../../../zaip-aios/guides/15-tools-e-codex.md":_,"../../../../zaip-aios/guides/16-lifecycle-e-reconciliacao.md":v,"../../../../zaip-aios/guides/17-como-o-custo-e-calculado.md":y,"../../../../zaip-aios/guides/18-catalogo-de-agentes.md":b,"../../../../zaip-aios/guides/19-assurance-e-autonomia.md":x,"../../../../zaip-aios/guides/20-instalacao-detalhada.md":S,"../../../../zaip-aios/guides/21-telemetria-monitor-custos.md":C,"../../../../zaip-aios/guides/22-fluxos-e-roteamento.md":w,"../../../../zaip-aios/guides/23-orquestracao-de-modelos.md":T,"../../../../zaip-aios/guides/24-calculo-de-custos-openai.md":E,"../../../../zaip-aios/guides/25-fontes-de-precos-openai.md":D,"../../../../zaip-aios/guides/26-qualidade-e-release.md":O,"../../../../zaip-aios/guides/27-telemetria-git-native.md":k,"../../../../zaip-aios/guides/28-lifecycle-completo.md":A});function F({locale:e,onClose:t}){let r=(0,j.useMemo)(()=>n(e,M,P),[e]),i=r.filter(e=>e.id!==`readme`),[a,o]=(0,j.useState)(`readme`),[s,c]=(0,j.useState)(`rendered`),l=r.find(e=>e.id===a)??r[0];return(0,N.jsx)(`div`,{className:`dashboard-help-backdrop`,children:(0,N.jsxs)(`section`,{"aria-label":e===`pt-BR`?`Ajuda do ZAIP-AIOS`:`ZAIP-AIOS help`,"aria-modal":`true`,className:`dashboard-help`,role:`dialog`,children:[(0,N.jsxs)(`header`,{children:[(0,N.jsxs)(`div`,{children:[(0,N.jsx)(`span`,{children:e===`pt-BR`?`Documentação local`:`Local documentation`}),(0,N.jsx)(`h2`,{children:e===`pt-BR`?`Ajuda e guides do framework`:`Framework help and guides`})]}),(0,N.jsx)(`button`,{"aria-label":e===`pt-BR`?`Fechar ajuda`:`Close help`,onClick:t,type:`button`,children:`×`})]}),(0,N.jsxs)(`div`,{className:`dashboard-help-layout`,children:[(0,N.jsxs)(`nav`,{"aria-label":e===`pt-BR`?`Documentos de ajuda`:`Help documents`,children:[(0,N.jsx)(`strong`,{children:e===`pt-BR`?`Visão geral`:`Overview`}),(0,N.jsx)(`button`,{className:a===`readme`?`is-active`:void 0,onClick:()=>o(`readme`),type:`button`,children:`README · ZAIP-AIOS`}),(0,N.jsx)(`strong`,{children:e===`pt-BR`?`Aprofundar no framework`:`Framework guides`}),i.map(e=>(0,N.jsx)(`button`,{className:a===e.id?`is-active`:void 0,onClick:()=>o(e.id),type:`button`,children:e.title},e.id))]}),(0,N.jsxs)(`article`,{children:[(0,N.jsxs)(`div`,{className:`dashboard-help-document-header`,children:[(0,N.jsx)(`h3`,{children:l?.title}),(0,N.jsxs)(`fieldset`,{"aria-label":e===`pt-BR`?`Visualização do documento`:`Document view`,children:[(0,N.jsx)(`button`,{"aria-pressed":s===`rendered`,className:s===`rendered`?`is-active`:void 0,onClick:()=>c(`rendered`),type:`button`,children:e===`pt-BR`?`Renderizado`:`Rendered`}),(0,N.jsx)(`button`,{"aria-pressed":s===`source`,className:s===`source`?`is-active`:void 0,onClick:()=>c(`source`),type:`button`,children:`Markdown`})]})]}),(0,N.jsx)(`div`,{className:`dashboard-help-sections`,children:U(l?.content??``,e).map(e=>(0,N.jsxs)(`section`,{children:[(0,N.jsx)(`h4`,{children:e.title}),s===`rendered`?(0,N.jsx)(I,{content:e.content}):(0,N.jsx)(`pre`,{children:e.content})]},e.title))})]})]})]})})}function I({content:e}){return H(L(e),V).map(({key:e,value:t})=>t.kind===`table`?(0,N.jsx)(`div`,{className:`dashboard-help-table-scroll`,children:(0,N.jsxs)(`table`,{children:[(0,N.jsx)(`thead`,{children:(0,N.jsx)(`tr`,{children:H(t.headers,e=>e).map(({key:e,value:t})=>(0,N.jsx)(`th`,{children:B(t)},e))})}),(0,N.jsx)(`tbody`,{children:H(t.rows,e=>e.join(``)).map(({key:e,value:t})=>(0,N.jsx)(`tr`,{children:H(t,e=>e).map(({key:e,value:t})=>(0,N.jsx)(`td`,{children:B(t)},e))},e))})]})},e):(0,N.jsx)(`pre`,{children:t.content},e))}function L(e){let t=e.split(`
+`),n=[],r=[],i=()=>{let e=r.join(`
+`).trim();e&&n.push({kind:`text`,content:e}),r=[]};for(let e=0;e<t.length;e+=1){let a=t[e],o=t[e+1];if(a?.includes(`|`)&&o&&R(o)){i();let r=z(a),o=[];for(e+=2;e<t.length&&t[e]?.includes(`|`);)o.push(z(t[e]??``)),e+=1;--e,n.push({kind:`table`,headers:r,rows:o});continue}r.push(a??``)}return i(),n}function R(e){return z(e).every(e=>/^:?-{3,}:?$/.test(e.replace(/\s/g,``)))}function z(e){return e.trim().replace(/^\|/,``).replace(/\|$/,``).split(`|`).map(e=>e.trim())}function B(e){return H(e.split(/(\*\*[^*]+\*\*)/g),e=>e).map(({key:e,value:t})=>t.startsWith(`**`)&&t.endsWith(`**`)?(0,N.jsx)(`strong`,{children:t.slice(2,-2)},e):(0,N.jsx)(j.Fragment,{children:t},e))}function V(e){return e.kind===`text`?`text:${e.content}`:`table:${e.headers.join(``)}:${e.rows.map(e=>e.join(``)).join(``)}`}function H(e,t){let n=new Map;return e.map(e=>{let r=t(e),i=(n.get(r)??0)+1;return n.set(r,i),{key:`${r}#${i}`,value:e}})}function U(e,t){return e.split(/\n(?=##?\s)/).filter(Boolean).map((e,n)=>{let r=e.trim().split(`
+`),i=r[0]?.match(/^#{1,2}\s+(.+)$/)?.[1];return{title:i??(n===0?t===`pt-BR`?`Introdução`:`Introduction`:t===`pt-BR`?`Seção ${n+1}`:`Section ${n+1}`),content:i?r.slice(1).join(`
+`).trim():r.join(`
+`).trim()}})}export{F as DashboardHelpDialog};