@zaip-ai/cli 1.0.4 → 1.0.7

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

@@ -0,0 +1,1320 @@
+import{n as e,t}from"./index-8AzCnl3a.js";import{t as n}from"./dashboard-localization-C98LGC-Q.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?
+`,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, evidencias e desvios.
+7. Depois dos demais descendentes, execute \`zaip-agent-finalizer\` como ultimo Sub-Run da Execution. Nenhum filho novo pode iniciar depois dele.
+8. Finalize a Run raiz com status tecnico e resultado terminal da Task separados.
+9. Execute os gates finais e documente rollback.
+
+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.
+
+\`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.
+`,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
+
+1. Delegue apenas subtarefas concretas e independentes.
+2. Dê a cada agente objetivo, limites, entradas e formato de saida.
+3. Evite dois agentes editando os mesmos arquivos.
+4. Centralize decisoes arquiteturais e integracao no agente responsavel.
+5. Exija evidencias, nao apenas declaracoes de conclusao.
+6. Use paralelismo somente quando reduzir caminho critico sem aumentar conflito.
+`,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-security\` | Escrita na raiz física do repositório, incluindo \`.git\`, \`.agents\`, \`.codex\` e demais arquivos ocultos | Limitada a \`github.com\` | Trabalho normal e princípio de menor privilégio, incluindo deploy GitHub autorizado |
+| \`zaip-aios-full-access\` | Escrita em \`C:\\\` inteiro no Windows, quando as permissões do sistema permitirem | Completa, todos os domínios | Correção de configuração, diagnóstico ou operação que realmente exija acesso fora do workspace |
+
+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.
+
+## \`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 deve ser o padrão para desenvolvimento, revisão, testes, manutenção normal e deploy GitHub autorizado quando a escrita na identidade SSH local for necessária. 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 deve ser ativado somente quando o perfil restrito não consegue executar uma operação
+legítima e explicitamente autorizada. Após a correção, volte para \`zaip-aios-security\`.
+
+## 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\`:** 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.
+
+## 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\` apenas 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 o Run pelo ID.\n2. Verifique duracao, tokens, custo, retries e retrabalho.\n3. Compare aceite planejado com evidencia produzida.\n4. Identifique gates lentos, contexto excessivo e chamadas repetidas.\n5. Agregue tendencias sem expor prompts ou segredos sensiveis.\n6. Converta achados recorrentes em Rule, Requirement ou melhoria de skill.\n\nRun e o envelope da chamada do `zaip-agent-orchestrator`; `parent_run_id` nulo identifica esse nivel. Sub-Run e a chamada de qualquer subagente e possui `parent_run_id`. Ambas fixam modelo e effort e agregam Calls, segmentos de uso, tokens e custo. Calls nao possuem tela ou lifecycle proprio. Operacao 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 so pode ser atribuido uma vez; uma correcao de duplicidade registra supersessao e preserva o evento historico. Inspecione `run_purpose`, pai e `agent_name`; agentes do catalogo usam `zaip-agent-*`. Diferencie status tecnico da chamada de agente e resultado terminal da Task. Reconcilie lifecycle globalmente apenas por comando humano explicito ou pelo popup confirmado; isso nao 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 foram observados ou reconciliados; valores indisponíveis permanecem `null`. Pensar sem criar permanece apenas em Conversas. Nunca atribua telemetria indisponível nem transforme ausência em zero.\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.
+- 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 analise read-only; cria Run intake e nenhuma Task.\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 coordena a DAG de uma ou mais Tasks.\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\nO ultimo filho de qualquer Execution e sempre o `zaip-agent-finalizer`. Ele aguarda todos os outros descendentes, cria uma barreira contra filhos posteriores e retorna uma decisao terminal restrita para a CLI aplicar. Toda Execution exige antes ao menos um executor elegivel pelas capacidades do catalogo. Status tecnico da chamada de agente e resultado do trabalho sao 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\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=e(),b=`# ZAIP-AIOS para Codex (Git-native)
+
+## Visão rápida
+
+O ZAIP-AIOS é um sistema operacional Git-native de engenharia autônoma para o Codex, criado para reduzir o custo e o tempo necessários à execução de trabalhos complexos. Sua meta é gerar uma economia estimada de 25% a 40% no consumo bruto de tokens ao longo de todo o ciclo de uma tarefa executada de maneira autônoma, e não apenas reduzir o custo de uma chamada isolada ao modelo.
+
+<img src=".agents/config/src/dashboard_pt_1_visao_geral.png" alt="Dashboard ZAIP-AIOS, Visão Geral" width="100%">
+
+Por meio de Graph Engineering, o sistema interpreta a demanda, decompõe entregas complexas em Tasks menores organizadas em uma DAG e seleciona, entre 18 agentes especializados, conforme capabilities, especialidade, escopo de escrita, dependências e risco declarados. Com Loop Engineering, o ZAIP-AIOS analisa, durante uma execução de Task, falhas, bloqueios e retrabalho. Quando a execução se origina de PRD ou SPEC e \`model_orchestration.mode:auto\` está ativo, ela começa pelo caminho mais econômico que preserve os gates de qualidade e pode escalar automaticamente entre os modelos GPT-5.6 Luna, Terra e Sol, com níveis de esforço low, medium, high ou xhigh, conforme os sinais da execução. Conversation e Task-first preservam a seleção manual do host/Codex.
+
+Requisitos, decisões, testes, revisões e evidências permanecem versionados e rastreáveis no Git, salvando o histórico sem precisar de um banco de dados. Uma tarefa só é considerada concluída quando existem provas objetivas e verificáveis de que os critérios de qualidade foram atendidos.
+
+| Se você quer… | Comece por… |
+| --- | --- |
+| Instalar e obter o primeiro resultado | [Instalação em um comando](#instalação-em-um-comando) |
+| Fazer uma alteração pontual | [Três formas de executar](#três-formas-de-executar) e [regras práticas](#regras-práticas-de-operação) |
+| Planejar uma entrega técnica ou de produto | [PRD como interface de autonomia](#prd-como-interface-de-autonomia) |
+| Conhecer os 18 agentes | [Personas e roteamento de agentes](#personas-e-roteamento-de-agentes) |
+| Entender estados, Runs e encerramento | [Cadeia completa de execução](#cadeia-completa-de-execução) e [Fluxos](#fluxos) |
+| Consultar custos, cobertura e rastreabilidade | [Dashboard Local](#dashboard-local) e [Telemetria Git-native](docs/TELEMETRIA-GIT-NATIVE.md) |
+| 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) |
+
+
+## Tese central
+
+| 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. |
+
+Essa separação é intencional: o GPT-5.6 fornece a inteligência, o Codex fornece o harness oficial de execução e o ZAIP-AIOS fornece a metodologia, a governança e a memória verificável do desenvolvimento. O ZAIP-AIOS define **o que deve ser feito, como o trabalho deve ser organizado, quais regras arquiteturais devem 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 continuam disponíveis para comparação e compatibilidade por meio de artefatos portáveis, sem reduzir o caminho oficial ao menor denominador comum.
+
+## Personas e roteamento de agentes
+
+O catálogo oficial de agentes fica em .agents/config/agents/catalog.yaml, separando identidade técnica da persona editável. O Dashboard permite alterar nome e cargo, recalcula automaticamente os identificadores derivados e impede mudanças inválidas. O comando adapters build atualiza as configurações locais do Codex sem sobrescrever preferências externas ao bloco gerenciado.
+
+O roteamento ocorre por especialidade e escopo: Doug cuida do frontend, Will do backend, Jonny de website, SEO e Agent Readiness, e Manu do design system. Bia é responsável por PRDs e Rafa por SPECs. A criação ou revisão desses artefatos exige uma Run ativa, delegada ao especialista correto, sem reutilização de execuções históricas ou atribuições artificiais.
+
+| Foto | # | Persona / função | Função |
+| :---: | ---: | --- | --- |
+| <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 grounded |
+| <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/LPs, SEO, GEO e readiness |
+| <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 |
+
+Consulte [Catálogo de agentes](docs/AGENT-CATALOG.md) para o contrato completo, capacidades e regras de roteamento.
+
+O fluxo pode começar por uma **Task**, por um **PRD** (*Product Requirements Document*, ou Documento de Requisitos do Produto) ou por uma **SPEC**, a especificação técnica desenvolvida segundo o conceito de **Spec-Driven Development (SDD)**. O PRD explica o problema, o resultado esperado, o contexto e os critérios do produto; a SPEC transforma essa intenção em escopo técnico, solução, Critérios de Aceite, Changes e uma DAG de Tasks executáveis.
+
+O ZAIP-AIOS não exige serviço em VPS, runtime concorrente ou roteamento obrigatório de modelos por API. O Codex permanece como host de execução; o ZAIP-AIOS acrescenta método, memória operacional, governança, rastreabilidade e observabilidade ao que acontece no projeto. O dashboard oferece Trabalho (Kanban) e Trabalho (Lista) para acompanhar Tasks, SPECs e PRDs, além do status, das dependências, dos bloqueios e do progresso do trabalho que múltiplos agentes executam de forma autônoma.
+
+> O desenvolvimento pode utilizar os tokens incluídos na conta ChatGPT/Codex, sem exigir consumo direto de API. O dashboard acompanha tokens, tempo e custo por tarefa e calcula o custo equivalente estimado de quanto o mesmo consumo representaria se fosse cobrado pelos preços de API. Essa comparação ajuda a prever custos antes de adotar uma execução via API e a dimensionar o benefício econômico aparente do plano em relação ao preço público da API, uma estimativa comparativa, não uma medição oficial de subsídio ou cobrança da OpenAI.
+
+## Dashboard Local
+
+O Dashboard local funciona como uma projeção dos registros Git-native, sem criar uma fonte de verdade paralela. Todas as informações exibidas podem ser reconstruídas a partir dos arquivos do projeto.
+
+As telas permitem acompanhar a execução, analisar consumo, investigar rastreabilidade e configurar o projeto, mantendo o Git como fonte oficial.
+
+### 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%">
+
+É a visão operacional com Trabalho (Kanban) e Trabalho (Lista). Ambas preservam os filtros Todas as Tarefas, Visão Unificada Geral, PRDs, SPECs e Tarefas Avulsas. A lista torna comparáveis status, origem, risco, Runs, Sub-Runs, tempo, tokens, custo e cobertura; o Kanban mantém a leitura por estágio. O usuário pode navegar pelos três níveis de execução, identificar bloqueios e abrir os detalhes rastreáveis de cada item.
+
+### 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%">
+
+Consolida tokens, tempo e custo por Run, Task, SPEC e PRD e permite analisar fases de conversa, planejamento e execução, além de trabalho novo e rework. Quando o Codex consome tokens ou franquia da conta em vez de cobrar uma API, o módulo calcula, quando há medição e pricing compatível, o **custo equivalente estimado de API** em USD e BRL. Essa estimativa serve para gestão e comparação; ela nunca é apresentada como cobrança real. As projeções preservam agregações por dia, mês e ano, médias, concentração de consumo e cobertura; valores não observados continuam \`unknown\`, nunca viram zero artificialmente.
+
+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. Consulte [Telemetria Git-native do Codex](docs/TELEMETRIA-GIT-NATIVE.md)
+para 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.
+
+### Configurar Agentes
+
+Apresenta o catálogo dos 18 agentes e permite configurar persona, modelo e esforço dentro dos contratos de identidade e roteamento do projeto.
+
+<img src=".agents/config/src/dashboard_pt_configuracao_agentes.png" alt="Dashboard ZAIP-AIOS, Configurar Agentes" width="100%">
+
+
+## Economia por tarefa: custo para concluir, não custo por chamada
+
+O preço de uma chamada, ou mesmo o preço de um modelo, não mede o custo real de desenvolvimento com IA. Uma Task costuma exigir várias chamadas: entendimento do pedido, leitura de contexto, implementação, execução de testes, correção, review, validação e registro da evidência. Por isso, o ZAIP-AIOS mede e compara **Runs, fases e rework por Task, SPEC e PRD**, em vez de celebrar uma chamada isolada barata.
+
+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 que o usuário governe o trabalho sem revisar cada decisão técnica.
+
+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.
+
+### 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
+
+Uma resposta pode parecer concluída mesmo sem testes, revisão ou comprovação dos Critérios de Aceite.
+
+Esse problema costuma reaparecer depois na forma de bugs, investigações, correções, regressões e novas rodadas de contexto.
+
+Tests, reviews, checks e Evidence adicionam um custo inicial, mas reduzem a chance e o impacto do retrabalho. Quando ele ainda ocorre, permanece registrado e rastreável.
+
+
+### Economia medida e meta central por tarefa
+
+Cada indicador abaixo mede uma parte diferente do fluxo. A primeira linha apresenta a faixa fundamentada/estimada para uma Task completa. As demais são medições reproduzíveis de contexto e payload. As medições da tabela são um snapshot de **13/07/2026**; elas não descrevem automaticamente a população atual de skills ou do repositório.
+
+Os percentuais não devem ser somados, pois as otimizações podem ocorrer simultaneamente no mesmo fluxo.
+
+Com ciclos constantes, as otimizações de payload medidas sustentam um piso conservador de **8%–15%**. Esse piso não é uma medição end-to-end da Task: a faixa de **25%–40%** é uma estimativa fundamentada para a Task completa, baseada no potencial adicional de reduzir ciclos e retrabalho com contexto seletivo, navegação compacta, budgets e checkpoints, verificação em lote e critérios/evidências claros.
+
+| O que é reduzido | O que representa | Baseline sem a otimização | Com ZAIP-AIOS | Economia | Situação da métrica |
+| --- | --- | ---: | ---: | ---: | --- |
+| **Task completa, todos os ciclos de modelo** | Entendimento, contexto, implementação, testes, correções, review e evidências até concluir uma Task. | Índice normalizado (**baseline = 100**) | **60–75** | **25%–40%** | **Estimativa fundamentada**; validar com Tasks pareadas piloto e cálculo amostral com telemetria coberta. |
+| **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. |
+
+A faixa de **25%–40%** aplica-se aos tokens brutos de todos os ciclos necessários para entregar uma Task, e não ao preço de uma única chamada. É uma estimativa operacional útil para planejamento, não uma economia financeira comprovada por tarefa nem uma comparação já demonstrada contra um baseline pareado.
+
+Para uma comparação válida, execute a mesma classe de Task em dois braços, por exemplo, Codex normal e Codex + ZAIP-AIOS, com o mesmo modelo, repositório, Critérios de Aceite e janela de observação. Compare:
+
+- 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\`; ele não converte ausência de telemetria em custo zero. Isso evita que uma estimativa de economia esconda custo de provider, rework ou qualidade não observados. Consulte também [a auditoria de tokens e performance](analysis/verificacao-auditoria-tokens-performance-zaip-aios-2026-07-13.md).
+
+## 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](docs/WORK-LIFECYCLE.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
+
+| 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** | Uma unidade idempotente por turno: \`interaction\` registra conversa sem Task artificial; \`delivery\` materializa e coordena trabalho, Changes e DAG quando aplicável. |
+| **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.
+
+Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex. Para executar trabalho de produto mais rápido, o único caminho suportado é uma Task-first realmente independente com Fast selecionado manualmente no Codex. Executions originadas por SPEC ou PRD usam sempre velocidade \`standard\`, inclusive em todas as Tasks descendentes; o ZAIP não oferece skill, hook ou override para mudar essa velocidade.
+
+Em todos os casos, cada turno observável resolve para uma Execution. \`prepare\` valida e congela o plano antes da mutação; \`execute\` reutiliza a Execution \`delivery\` para materializar Change e Task; cada Execution usa uma Run raiz do orquestrador, ao menos um Sub-Run executor elegível e o \`zaip-agent-finalizer\` obrigatório por último. 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](docs/ASSURANCE-E-AUTONOMIA.md).
+
+## Princípios de engenharia autônoma
+
+- **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.
+
+Toda mensagem do usuário cria uma Execution e uma Run de captura. Perguntas, feedbacks e análises read-only usam Execution \`interaction\`, sem Task ou Change artificial. A criação ou o refinamento explícito de PRD/SPEC \`draft\` é a exceção de definição: a própria \`interaction\` pode persistir esses macros e o PreparedPlan sem Task, Change ou Execution \`delivery\`. Fora dessa exceção, pedido avulso direto materializa e inicia a mesma Execution \`delivery\`, Task, Change e Run raiz de orquestração antes da primeira mutação; somente 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 ZAIP-AIOS aplica **Graph Engineering** para coordenar 18 agentes especializados como um grafo de execução governado por capacidades, dependências, criticidade, custo e evidências. O papel de **Graph Engineer** é exercido pela orquestração: a cada etapa, ela interpreta a demanda e escolhe o menor conjunto de agentes necessário. A calibração automática entre **Luna**, **Terra** e **Sol** e entre os esforços **low**, **medium**, **high** e **xhigh** aplica-se somente a Agent Runs originadas de PRD/SPEC quando \`model_orchestration.mode:auto\` está ativo; Conversation e Task-first preservam a seleção manual do host/Codex.
+
+Essa autonomia é governada: Dave é a raiz única, cada executor recebe apenas o escopo necessário, Nanda realiza a revisão independente, especialistas de assurance entram somente quando existem sinais objetivos e Gui encerra o fluxo por último. Em execuções originadas por PRD ou SPEC, os sinais de fase, complexidade, ambiguidade, transversalidade, rework, impacto e rollback alimentam automaticamente a seleção. Tasks avulsas e conversas preservam a seleção manual do host enquanto não possuem um \`model_profile\` governado equivalente.
+
+O papel de **Loop Engineer** aparece quando a primeira tentativa não satisfaz os gates. O resultado volta para Dave, o rework é classificado e uma nova Agent Run pode subir de **Luna → Terra → Sol** ou de **low → medium → high → xhigh** quando os novos sinais justificarem o custo. O modelo não muda silenciosamente dentro da mesma Run: cada tentativa permanece auditável, com configuração, tokens, custo, evidências e resultado próprios. Assim, a execução é autônoma dentro de limites explícitos, começando pelo caminho mais barato que preserve a qualidade e escalando somente quando a evidência da tentativa exigir.
+
+### Grafo principal
+
+Este é o caminho mais comum e econômico. Todos os agentes são filhos diretos da mesma orquestração de Dave; a sequência lógica não significa que um trabalhador chama o próximo.
+
+\`\`\`mermaid
+flowchart LR
+    I["Entrada"] --> C["Classificar demanda"]
+    C --> D["Dave<br/>orquestrador"]
+    D --> E{"Executor por capacidade"}
+    E -->|Task genérica| L["Leo"]
+    E -->|Trabalho técnico amplo| R["Rafa"]
+    E -->|Domínio específico| S["Especialista"]
+    L --> D
+    R --> D
+    S --> D
+    D --> N["Nanda<br/>review independente"]
+    N -->|Aprovado| D
+    N -->|Rework| D
+    D --> G["Gui<br/>finalizador"]
+    G --> O["Resultado terminal"]
+\`\`\`
+
+\`\`\`text
+Dave → um executor ou especialista → Nanda → Gui
+\`\`\`
+
+### Loop de custo e qualidade
+
+O diagrama abaixo representa a política automática para execuções originadas de PRD/SPEC com \`model_orchestration.mode:auto\`. Em Conversation e Task-first, o host/Codex mantém a seleção manual de modelo e effort.
+
+\`\`\`mermaid
+flowchart LR
+    A["Tentativa"] --> V{"Gates e review passaram?"}
+    V -->|Sim| F["Finalizar"]
+    V -->|Não| R["Classificar rework"]
+    R --> C["Recalibrar agente, modelo e esforço"]
+    C -->|Simples e delimitado| L["Luna / low"]
+    C -->|Execução padrão| T["Terra / medium"]
+    C -->|Ambíguo, transversal ou rework estrutural| S["Sol / high ou xhigh"]
+    L --> A
+    T --> A
+    S --> A
+\`\`\`
+
+O escalonamento não é obrigatório em toda falha. Um erro determinístico pode continuar barato; a classificação \`critical\` amplia os guards de assurance, mas não eleva mecanicamente o executor. Sol e \`xhigh\` são reservados para ambiguidade, transversalidade, review/audit, rework estrutural ou dificuldade observável.
+
+<details>
+<summary><strong>Formas de entrada</strong></summary>
+
+\`\`\`mermaid
+flowchart TD
+    U["Solicitação"] --> T{"Tipo de entrada"}
+    T -->|Pergunta simples| Q["Resposta direta"]
+    T -->|Análise especializada| A["Interaction"]
+    T -->|Mudança delimitada| K["Task-first"]
+    T -->|Problema de produto| P["PRD"]
+    T -->|Definição técnica| S["SPEC"]
+    T -->|Continuação| C["Retomar foco"]
+    T -->|Falha ou achado| W["Rework"]
+    T -->|Auditoria| X["Audit"]
+    T -->|Deploy ou push| Git["Git-only"]
+    A --> D["Dave"]
+    K --> D
+    P --> B["Bia"]
+    S --> R["Rafa"]
+    C --> D
+    W --> D
+    X --> D
+    B --> D
+    R --> D
+\`\`\`
+
+</details>
+
+<details>
+<summary><strong>Planejamento com PRD e SPEC</strong></summary>
+
+\`\`\`mermaid
+flowchart LR
+    I["Ideia ou problema"] --> D["Dave"]
+    D --> B["Bia<br/>PRD e critérios"]
+    B --> D
+    D --> R["Rafa<br/>SPEC e DAG técnica"]
+    R --> D
+    D --> V{"Pronto para executar?"}
+    V -->|Refinar produto| B
+    V -->|Refinar técnica| R
+    V -->|Sim| X["Materializar Tasks"]
+    X --> E["Executar DAG"]
+    E --> N["Nanda"]
+    N --> G["Gui"]
+\`\`\`
+
+</details>
+
+<details>
+<summary><strong>Demanda crítica e transversal</strong></summary>
+
+\`\`\`mermaid
+flowchart TD
+    I["Demanda crítica"] --> D["Dave<br/>orquestração"]
+    D --> P["Bia ou Rafa<br/>planejamento"]
+    P --> D
+
+    D --> B1["Will<br/>backend"]
+    D --> B2["Doug<br/>frontend"]
+    D --> B3["Manu<br/>design"]
+    D --> B4["Dan<br/>cloud"]
+
+    B1 --> D
+    B2 --> D
+    B3 --> D
+    B4 --> D
+
+    D --> DI["Dani<br/>integração quando necessária"]
+    DI --> D
+    D --> N["Nanda<br/>review obrigatório"]
+    N --> D
+
+    D --> SEC{"Há segurança ou dados críticos?"}
+    SEC -->|Sim| L["Luiz<br/>security audit"]
+    SEC -->|Não| CRIT{"Há release, alto risco ou auditoria ampla?"}
+    L --> D
+    D --> CRIT
+    CRIT -->|Sim| A["Ana<br/>auditoria independente"]
+    CRIT -->|Não| G["Gui"]
+    A --> D
+    D --> G["Gui<br/>último agente"]
+\`\`\`
+
+Nanda cobre a revisão independente normal. Luiz é adicional quando há segurança ou dados críticos. Ana é adicional para alto risco, release ou reprodução ampla de evidências. Uma demanda pode usar Nanda, Luiz e Ana quando todos os guards forem verdadeiros.
+
+</details>
+
+<details>
+<summary><strong>Seleção de modelo e esforço</strong></summary>
+
+\`\`\`mermaid
+flowchart TD
+    A["Agente selecionado"] --> F["Identificar papel e fase"]
+    F --> S["Ler sinais persistidos"]
+    S --> R["Classificar criticidade"]
+    R --> O{"Override explícito válido?"}
+    O -->|Execution| OE["Override da Execution"]
+    O -->|Task| OT["Override da Task"]
+    O -->|Não| P["Política automática"]
+    P --> X{"Perfil da Agent Run"}
+    X -->|Simples, local e verificável| L["Luna / low"]
+    X -->|Execução standard| T["Terra / medium"]
+    X -->|Crítico e tecnicamente claro| TH["Terra / medium + assurance"]
+    X -->|Planejamento ou ambiguidade alta| SH["Sol / medium ou high"]
+    X -->|Múltiplos gatilhos excepcionais| SX["Sol / xhigh"]
+    OE --> V["Validar capacidades do host"]
+    OT --> V
+    L --> V
+    T --> V
+    TH --> V
+    SH --> V
+    SX --> V
+    V --> RUN["Abrir Agent Run imutável"]
+\`\`\`
+
+\`\`\`text
+Modelo = papel + fase + complexidade + ambiguidade + transversalidade
+Esforço = criticidade + dificuldade de raciocínio + custo do erro
+Assurance = criticidade + impacto + rollback
+\`\`\`
+
+</details>
+
+<details>
+<summary><strong>Matriz recomendada por agente</strong></summary>
+
+| Agente | Lite | Standard | Crítico |
+|---|---|---|---|
+| Dave | Terra/medium | Terra/medium | Sol/medium ou high somente em planejamento, ambiguidade ou transversalidade |
+| Rafa | Luna/low quando simples e delimitado | Terra/medium | Terra/medium; risco critical amplia assurance, não o modelo mecanicamente |
+| Leo | Luna/low quando simples e delimitado | Terra/medium | Terra/medium; Sol/high apenas por ambiguidade, transversalidade ou rework estrutural |
+| Bia | Terra/medium | Sol/medium | Sol/high quando o trabalho analítico for complexo ou ambíguo |
+| Gui | Terra/medium | Terra/medium | Terra/medium; o finalizer avalia Evidence já produzida e não escala automaticamente |
+| Nanda | Sol/medium | Sol/medium | Sol/high quando a revisão for complexa |
+| Dani | Terra/medium | Terra/medium | Terra/medium; integração não escala automaticamente |
+| Ana | Não acionar | Somente excepcional | Sol/high ou xhigh |
+| Lia | Luna/low | Luna/medium ou Terra/medium | Terra/high |
+| Gabi | Luna/low para cálculo mecânico | Terra/medium | Sol/high para diagnóstico causal complexo |
+| Tati | Terra/low | Terra/medium | Sol/high ou xhigh estrutural |
+| Doug | Luna/low | Terra/medium | Sol/high somente se transversal |
+| Will | Luna/low | Terra/medium | Sol/high para arquitetura ou risco material |
+| Jonny | Luna/low | Terra/medium | Sol/high para SEO, GEO ou arquitetura complexos |
+| Manu | Luna/low para aplicação de tokens | Terra/medium | Sol/high para mudança visual central |
+| Dan | Luna/low para configuração local | Terra/medium | Sol/high para infraestrutura crítica |
+| Luiz | Não acionar | Sol/medium quando necessário | Sol/high ou xhigh |
+| Lucia | Luna/low para variações | Terra/medium | Sol/high para estratégia ambígua |
+
+</details>
+
+<details>
+<summary><strong>Perfis por criticidade</strong></summary>
+
+| Perfil | Orquestração | Execução | Review | Assurance adicional | Finalização |
+|---|---|---|---|---|---|
+| Lite | Dave, Terra/low | Luna/low | Nanda, Terra/low | Não | Gui, Terra/low |
+| Standard | Dave, Terra/medium | Terra/medium | Nanda, Terra/medium | Dani, Luiz ou Ana somente por guard | Gui, Terra/medium |
+| Critical | Dave, Terra/medium; Sol somente se planejamento, ambiguidade ou transversalidade exigirem | Terra/medium para execução tecnicamente clara; Sol/high por ambiguidade, transversalidade ou rework estrutural | Nanda, Sol/high quando a revisão for complexa | Dani, Terra/medium, por integração; Luiz ou Ana, Sol/high, pelos guards aplicáveis | Gui, Terra/medium |
+
+</details>
+
+### Grafo unificado dos 18 agentes
+
+\`\`\`mermaid
+flowchart TD
+    IN["Conversa, Task, SPEC, PRD, Rework ou Audit"] --> CL["Classificar intenção, capacidade e risco"]
+    CL -->|Sem delegação necessária| OUT["Resposta direta"]
+    CL --> D0["Dave<br/>seleciona a execução"]
+
+    D0 --> MC["Calibrar modelo e esforço da Agent Run"]
+    MC --> ROUTE{"Capacidade requerida"}
+
+    ROUTE --> BIA["Bia<br/>produto e PRD"]
+    ROUTE --> RAFA["Rafa<br/>SPEC e técnica ampla"]
+    ROUTE --> LEO["Leo<br/>Task genérica"]
+    ROUTE --> LIA["Lia<br/>documentação"]
+    ROUTE --> GABI["Gabi<br/>dados e métricas"]
+    ROUTE --> TATI["Tati<br/>refatoração"]
+    ROUTE --> DOUG["Doug<br/>frontend"]
+    ROUTE --> WILL["Will<br/>backend"]
+    ROUTE --> JONNY["Jonny<br/>website"]
+    ROUTE --> MANU["Manu<br/>design system"]
+    ROUTE --> DAN["Dan<br/>cloud"]
+    ROUTE --> LUCIA["Lucia<br/>marketing"]
+
+    BIA --> D1["Dave<br/>recebe resultados"]
+    RAFA --> D1
+    LEO --> D1
+    LIA --> D1
+    GABI --> D1
+    TATI --> D1
+    DOUG --> D1
+    WILL --> D1
+    JONNY --> D1
+    MANU --> D1
+    DAN --> D1
+    LUCIA --> D1
+
+    D1 --> INT{"Há branches para integrar?"}
+    INT -->|Sim| DANI["Dani<br/>integração"]
+    DANI --> D2["Dave<br/>recebe candidato integrado"]
+    INT -->|Não| D2
+
+    D2 --> REVIEW["Nanda<br/>review independente obrigatório"]
+    REVIEW -->|Rework| RW["Dave<br/>classifica rework e abre nova Agent Run"]
+    RW --> MC
+    REVIEW -->|Aprovado| SEC{"Segurança ou dados críticos?"}
+
+    SEC -->|Sim| LUIZ["Luiz<br/>security audit"]
+    LUIZ --> D3["Dave<br/>recebe avaliação de segurança"]
+    SEC -->|Não| D3
+    D3 --> AUDIT{"Alto risco, release ou auditoria ampla?"}
+
+    AUDIT -->|Sim| ANA["Ana<br/>auditoria independente"]
+    ANA --> D4["Dave<br/>recebe auditoria terminal"]
+    AUDIT -->|Não| D4
+    D4 --> GUI["Gui<br/>finalizador obrigatório e último"]
+
+    GUI --> TERM["Completed, blocked,<br/>failed ou cancelled"]
+\`\`\`
+
+O grafo comum usa quatro agentes. Os demais entram por guards de capacidade, dependência ou risco; o objetivo não é usar todos os 18 em toda demanda. Consulte o [guia completo de Graph Engineering dos agentes](guide/GRAPH-ENGINEERING-AGENTES-ZAIP.md) para os contratos dos nós, cenários detalhados e regras de escalada.
+
+## Fluxos
+
+### Seis etapas principais e três saídas alternativas
+
+O lifecycle possui seis etapas no caminho de sucesso. \`Bloqueado\`, \`Falhado\` e \`Cancelado\` são saídas alternativas: elas podem interromper o fluxo, mas não são etapas pelas quais todo trabalho precisa passar.
+
+| Etapa | O que acontece | Estados Git-native mais comuns |
+| --- | --- | --- |
+| **1. Definição** | Registra problema, objetivo, escopo e Critérios de Aceite no PRD, que ainda pode ser refinado sem iniciar implementação. | PRD \`draft\` |
+| **2. Planejamento** | A SPEC \`draft\` detalha o trabalho, suas dependências, Changes previstos, DAG e estratégia de verificação. Uma Task não percorre esta etapa. | SPEC \`draft\`; PreparedPlan em construção |
+| **3. Pronto para Executar** | O plano foi validado, materializado e está apto a iniciar. Uma Task preparada entra no lifecycle por esta etapa. | PRD/SPEC \`ready\`; Task/Change \`planned\`; Execution \`planned\` |
+| **4. Execução** | Cada Task recebe sua própria orquestração, agentes elegíveis e ciclos de implementação ou correção. | PRD/SPEC \`active\`; Task/Change \`executing\`; Execution/Run \`running\` |
+| **5. Verificação** | Tests, reviews, evals, checks, Decisions e Evidence comprovam os Critérios de Aceite. SPEC e PRD fazem também sua verificação parental. | Change/Execution \`verifying\` |
+| **6. Concluído** | O resultado foi verificado e o nível correspondente foi encerrado. | Task/Change/Execution \`completed\`; PRD/SPEC \`delivered\` |
+| **Bloqueado** | Existe uma dependência ou impedimento recuperável. O trabalho pode continuar depois com \`resume\` ou \`rework\`. | \`blocked\` |
+| **Falhado** | Um impedimento técnico ou externo impede continuar com segurança após os retries permitidos, por exemplo, permissão negada, Codex/provider indisponível, falha de internet/rede ou erro em uma ferramenta obrigatória. | \`failed\` |
+| **Cancelado** | Uma pessoa encerra pontualmente o trabalho por decisão explícita; nunca é uma saída automática do agente. | \`cancelled\` |
+
+### Visão macro: cada tipo mantém seu próprio fluxo
+
+Task, SPEC e PRD não se misturam em uma única linha de execução. Uma SPEC coordena suas Tasks; um PRD coordena suas SPECs; e cada Task continua sendo executada e verificada de forma independente.
+
+Os três fluxos aparecem lado a lado em uma única imagem PNG, preservando a leitura no preview e deixando explícito que SPEC e PRD coordenam entregas sem fundir o lifecycle de cada Task.
+
+Uma Task não passa pelas etapas 1 e 2: quando preparada, ela começa em **3. Pronto para Executar**; quando direta, começa em **4. Execução**.
+
+![Lifecycles de Task, SPEC e PRD](docs/assets/diagrams/lifecycles-task-spec-prd.png)
+
+Conversation permanece fora dessas três linhas: ela usa uma Execution \`interaction\`, pode consultar agentes e termina em uma resposta sem criar Task artificial.
+
+### Orquestração de uma Task
+
+A Task é a unidade de execução do ZAIP. Para concluí-la, o sistema pode executar mais de um ciclo de orquestração, mas cada ciclo tem uma Run raiz, agentes com responsabilidades bem definidas, limites de tentativa e um resultado explícito. Isso evita que uma sequência longa de chamadas pareça uma única execução sem começo, fim ou responsável.
+
+O \`Zaip Agent Orchestrator\` conduz o ciclo e delega a implementação ou a correção ao \`Zaip Agent Executor\`. Enquanto o trabalho acontece, Evidence e Decisions registram o que foi feito, como foi validado e quais escolhas foram tomadas. Em seguida, o \`Zaip Agent Reviewer\` assume a verificação independente dos Critérios de Aceite, executando ou coordenando Tests, Checks e Evals. Quando a profundidade de prova exigir, o \`Zaip Agent Auditor\` acrescenta uma revisão adicional. Só então o \`Zaip Agent Finalizer\` recebe o resultado já verificado, consolida as evidências e fecha a Run raiz como o último Sub-Run: depois desse ponto, nenhuma nova chamada pode ser anexada ao ciclo.
+\`\`\`mermaid
+flowchart TD
+    TASK["Task em Execução"] --> ORCH["Zaip Agent Orchestrator<br/>Run raiz do ciclo N"]
+    ORCH --> EXECUTOR["Zaip Agent Executor<br/>implementação ou correção"]
+    EXECUTOR --> EVIDENCE["Coleta contínua durante a execução<br/>Evidence + Decisions registradas"]
+    EVIDENCE --> REVIEWER["Zaip Agent Reviewer<br/>executa e coordena a verificação"]
+    REVIEWER --> QUALITY["Camadas de validação<br/>Tests + Checks + Evals"]
+    QUALITY -->|validação suficiente| VERIFIED["Resultado verificado<br/>antes do fechamento"]
+    QUALITY -->|auditoria necessária| AUDITOR["Zaip Agent Auditor<br/>verificação adicional"]
+    AUDITOR --> VERIFIED
+    VERIFIED --> FINALIZER["Zaip Agent Finalizer<br/>consolida e encerra o ciclo"]
+    FINALIZER --> OUTCOME{"Resultado já verificado"}
+
+    OUTCOME -->|impedimento técnico, externo ou retries esgotados| FAILED["Falhado<br/>permissão, Codex/provider, internet/rede<br/>ou ferramenta impedem continuar"]
+    OUTCOME -->|critérios atendidos| DONE["Concluído"]
+    OUTCOME -->|condição recuperável| BLOCKED["Bloqueado<br/>aguarda condição"]
+    OUTCOME -->|correção necessária| REWORK["Rework necessário<br/>novo ciclo N + 1"]
+    OUTCOME -.-> HUMAN["Ação humana pontual<br/>solicitação de pausa"]
+    HUMAN --> CANCELLED["Cancelado"]
+
+    BLOCKED -->|resume dentro da política| ORCH
+    REWORK -->|novo ciclo dentro da política| ORCH
+
+    classDef entry fill:#2563eb,color:#fff,stroke:#1d4ed8,stroke-width:2px;
+    classDef agent fill:#6d28d9,color:#fff,stroke:#a78bfa;
+    classDef executor fill:#1e3a8a,color:#fff,stroke:#60a5fa,stroke-width:2px;
+    classDef reviewer fill:#c2410c,color:#fff,stroke:#fb923c,stroke-width:2px;
+    classDef auditor fill:#166534,color:#fff,stroke:#4ade80,stroke-width:2px;
+    classDef finalizer fill:#991b1b,color:#fff,stroke:#ef4444,stroke-width:2px;
+    classDef info fill:#334155,color:#fff,stroke:#94a3b8;
+    classDef success fill:#15803d,color:#fff,stroke:#4ade80,stroke-width:2px;
+    classDef warning fill:#a16207,color:#fff,stroke:#facc15;
+    classDef failure fill:#b91c1c,color:#fff,stroke:#f87171;
+
+    class TASK entry;
+    class ORCH agent;
+    class EXECUTOR executor;
+    class REVIEWER reviewer;
+    class AUDITOR auditor;
+    class FINALIZER finalizer;
+    class EVIDENCE,QUALITY,VERIFIED,OUTCOME,HUMAN info;
+    class DONE success;
+    class BLOCKED,REWORK,CANCELLED warning;
+    class FAILED failure;
+\`\`\`
+O encerramento nunca decide sozinho se o trabalho está pronto: essa decisão já foi sustentada pelo Reviewer, pelas camadas de validação e, quando necessário, pelo Auditor. A partir daí, o fluxo separa claramente o resultado funcional da Task do status técnico da Run.
+
+- **Concluído:** os Critérios de Aceite foram comprovados e a entrega está pronta.
+- **Bloqueado:** há uma condição recuperável; o ciclo pode ser retomado dentro da política configurada.
+- **Rework necessário:** a validação encontrou uma correção necessária; um novo ciclo é iniciado com o contexto e as evidências anteriores.
+- **Falhado:** um impedimento técnico ou externo, como permissão insuficiente, indisponibilidade do Codex ou provider, falha de rede ou ferramenta, ou tentativas esgotadas, impede continuar com segurança.
+- **Cancelado:** uma pessoa solicitou explicitamente a interrupção; não é uma decisão automática do fluxo.
+
+Bloqueio e rework não descartam o que já foi produzido. Eles retornam ao Orchestrator para um novo ciclo controlado, respeitando os limites de retries, orçamento e política da Execution.
+
+### Regras práticas de operação
+
+#### Entrada e preparação
+
+- **Conversation:** usa uma Execution \`interaction\` e termina em resposta, sem criar Task artificial.
+- **Task direta:** a captura cria Task, Change e Execution e inicia a execução imediatamente.
+- **Task preparada:** permanece em Pronto para Executar até o comando \`execute\`.
+- **SPEC:** coordena a DAG de suas Tasks, mas cada Task mantém execução, Run e evidências próprias.
+- **PRD:** coordena as SPECs selecionadas no PreparedPlan, sem fundir os seus lifecycles.
+
+Task direta e Task preparada seguem a mesma trilha controlada, mas refinamentos e reworks podem criar novos ciclos de orquestração. Cada novo ciclo começa explicitamente por \`execute\`, \`resume\` ou \`rework\` e respeita os limites de retries e reparos da Execution.
+
+O prepare automático atende somente uma Task sem dependências. Para uma DAG manual, construa e valide o plano antes de preparar a Task:
+
+\`\`\`bash
+zaip plan build --draft DRAFT.json --output PLAN.json
+zaip plan validate --plan PLAN.json
+zaip task prepare TASK-ID --plan PLAN.json
+\`\`\`
+
+Um PRD precisa ter pelo menos uma SPEC para chegar a \`ready\`, \`active\` ou \`delivered\`. A entrega considera apenas as SPECs selecionadas no seu PreparedPlan; SPECs fora desse plano não são encerradas implicitamente.
+
+#### Refinamento Git-native
+
+Enquanto PRD ou SPEC estiverem em \`draft\`, refine diretamente o Markdown versionado, incrementando \`revision\` e \`updated_at\`. Depois de \`prepare\`, não altere silenciosamente o plano materializado: uma mudança semântica exige a transição explícita suportada de volta para draft ou a criação de um novo draft.
+
+#### Verificação e encerramento
+
+Os Sub-Runs executores produzem a implementação enquanto Evidence e Decisions registram continuamente provas e escolhas relevantes. Em seguida, o \`Zaip Agent Reviewer\` executa ou coordena Tests, Checks e Evals para verificar os Critérios de Aceite; o \`Zaip Agent Auditor\` pode acrescentar uma checagem independente. Somente depois dessas etapas o \`Zaip Agent Finalizer\`, papel canônico \`zaip-agent-finalizer\`, consolida o resultado já verificado e encerra a sequência de Sub-Runs como barreira final do ciclo.
+
+Depois do Finalizer, encerre a Run raiz mantendo separados o status técnico da Run e o resultado funcional da Task:
+
+\`\`\`bash
+zaip run finish RUN-ID \\
+  --status completed \\
+  --task-outcome completed
+zaip run closure RUN-ID
+\`\`\`
+
+Substitua \`completed\` em \`--task-outcome\` por \`blocked\`, \`failed\` ou \`cancelled\` quando esse for o resultado funcional verificado da Task.
+
+Gates estruturais disponíveis incluem:
+
+\`\`\`bash
+zaip architecture validate
+zaip modules validate
+zaip profile validate
+zaip cqrs validate # quando aplicável
+\`\`\`
+
+\`zaip run reconcile --open\` é um reparo global manual. No dashboard, ele só é executado depois de confirmação explícita no popup.
+
+#### Observabilidade e projeções
+
+Use \`zaip run list\` para navegar pelas Runs e \`zaip run aggregate\` para agregar tokens e custos no escopo desejado. O dashboard, o Kanban e o Cost Monitor são projeções do estado Git-native; eles não substituem os records canônicos.
+
+Conversation, Planning e Execution permanecem separados. Tokens, custos, tempo, performance e rework podem ser analisados por Task, SPEC e PRD. Valores indisponíveis continuam como \`unknown\` ou \`null\`: totais, estimativas e cobertura nunca transformam ausência de telemetria em zero.
+
+## Estrutura atual de \`.agents\`
+
+\`\`\`text
+.agents/
+├── config/
+│   ├── project.yaml
+│   ├── framework.lock.yaml
+│   ├── agents/catalog.yaml
+│   └── profiles/clients.yaml
+├── dashboard/
+│   ├── zaip-dashboard.exe
+│   ├── apps/frontend/
+│   ├── modules/{operations,cost-monitor,traceability}/
+│   ├── packages/
+│   └── tests/e2e/
+├── design/
+│   ├── DESIGN.md
+│   ├── tokens.json
+│   ├── zaip-design.exe
+│   ├── apps/catalog/
+│   └── packages/
+├── 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/{manifest.json,summary.json,entity-snapshot.json}/
+│   └── telemetry/<ano>/<mês>/writers/<writer-id>/{manifest.json,chunks/}
+├── rules/
+│   ├── zaip/{core,workflow,architecture,security,context,evolution}.md
+│   └── project/            # Rules personalizadas deste projeto
+├── requirements/
+├── skills/
+├── tools/
+│   ├── catalog.yaml
+│   ├── {mcp,api}/
+│   ├── policies/
+│   ├── profiles/
+│   ├── runtime/
+│   └── servers/
+├── zaip-aios/
+│   ├── INDEX.md
+│   └── guides/
+├── .env.example
+└── .gitignore
+.agents/runtime/
+└── local/                               # estado local ignorado pelo Git
+    ├── claims/                          # claims atômicos de lifecycle
+    └── codex-telemetry-spool/v1/        # captura sanitizada, privada e recuperável
+\`\`\`
+
+| 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 grafo de rastreabilidade; lê os manifests de lifecycle e os detalhes canônicos por ID, sem criar uma verdade paralela nem reconstruir arquivos locais. |
+| \`design/\` | Design system do ZAIP, tokens visuais, catálogo de componentes e launcher local de inspeção. |
+| \`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/\` | Estado específico da máquina, como claims de lifecycle, writer ID e spool sanitizado de telemetria; fica fora do Git e não é uma fonte do dashboard. Segredos nunca devem ser gravados nos registros. |
+
+\`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 read-only é uma implementação técnica em \`packages/local-runtime\`, e não um \`apps/backend\`. Os módulos \`operations\`, \`cost-monitor\` e \`traceability\` formam os read models em memória a partir dos manifests canônicos. \`zaip-dashboard.exe\` permanece diretamente em \`.agents/dashboard\` e também é instalado pelo CLI oficial.
+
+## Arquitetura das aplicações
+
+Quando essas superfícies existirem, use 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\`. Essas pastas descrevem aplicações do produto consumidor, não o dashboard ZAIP. \`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. O gate ignora código gerado, distribuição, vendor, dados e lockfiles. Exceções temporárias cobrem somente legado não-dashboard, têm limite congelado, responsável, motivo e validade.
+
+## Desenvolvimento do framework
+
+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.
+
+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 gera \`.codex/config.toml\` com dois perfis de permissão. O perfil efetivo é
+selecionado por \`default_permissions\`; ele define o limite técnico que o processo pode alcançar,
+enquanto instruções, Rules, hooks e skills definem o que o agente está autorizado a fazer.
+
+| Perfil | Filesystem nativo no Windows | Rede de comandos | Quando usar |
+| --- | --- | --- | --- |
+| \`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\` | Desenvolvimento, revisão, testes e deploy GitHub autorizado: é o perfil recomendado para o trabalho normal. |
+| \`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 | Exceção temporária para uma operação explicitamente autorizada que realmente exija acesso fora do workspace. |
+
+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.
+
+Use-o somente depois de diagnosticar que \`zaip-aios-security\` não atende uma necessidade legítima
+e explicitamente autorizada. Não o selecione apenas para contornar uma negação de permissão. Ao
+concluir a operação excepcional, retorne para \`zaip-aios-security\` e reinicie completamente o
+Codex para que o sandbox materialize o perfil selecionado.
+
+### 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\`, que bloqueia escapes do repositório, referências diretas a segredos, Git destrutivo, force push, mutações de OS, ACL, persistência, elevação e banco destrutivo;
+- 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\` e 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).
+
+## Instalação em um comando
+
+Com Node.js 22 ou mais recente e Git disponíveis, abra o terminal na raiz do repositório que receberá o ZAIP-AIOS e execute:
+
+\`\`\`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 abaixo representa o estado atual deste 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. Ele também instala os adapters \`AGENTS.md\` e \`CLAUDE.md\`, a skill 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. Esses arquivos apontam cada cliente 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, use o [índice operacional](.agents/zaip-aios/INDEX.md) para abrir somente o guia necessário sobre primeiros passos, execução, revisão, custos, ferramentas, diagnóstico ou atualização.
+
+### 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.
+
+O navegador integrado não é ativado silenciosamente pelo CLI nem por \`.codex/config.toml\`. No app Codex/ChatGPT para desktop, o plugin Browser permite abrir páginas e aplicações locais, clicar, digitar, inspecionar o estado renderizado, capturar screenshots e verificar visualmente uma implementação, sempre sujeito às permissões de sites e às confirmações de ações sensíveis. O navegador integrado não está disponível no Codex CLI nem na extensão de IDE. Para automação por Playwright ou outro MCP de navegador, \`.agents/tools\` inclui um manifesto opt-in desabilitado por padrão; a implementação precisa ser escolhida, auditada e validada antes da ativação.
+
+## 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, gere ou atualize o vault com:
+
+\`\`\`powershell
+node .agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.mjs
+\`\`\`
+
+Cada pessoa que baixar o repositório pode executar esse comando no próprio computador. Para instalar o aplicativo, abrir a pasta correta como vault, gerar somente uma Task e atualizar a projeção depois de um \`git pull\`, consulte o [guia de Obsidian para rastreabilidade ZAIP](guide/CRIAR-PASTA-OBSIDIAN.md).
+`,x=t(),S=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});function C({locale:e,onClose:t}){let r=(0,y.useMemo)(()=>n(e,b,S),[e]),i=r.filter(e=>e.id!==`readme`),[a,o]=(0,y.useState)(`readme`),[s,c]=(0,y.useState)(`rendered`),l=r.find(e=>e.id===a)??r[0];return(0,x.jsx)(`div`,{className:`dashboard-help-backdrop`,children:(0,x.jsxs)(`section`,{"aria-label":e===`pt-BR`?`Ajuda do ZAIP-AIOS`:`ZAIP-AIOS help`,"aria-modal":`true`,className:`dashboard-help`,role:`dialog`,children:[(0,x.jsxs)(`header`,{children:[(0,x.jsxs)(`div`,{children:[(0,x.jsx)(`span`,{children:e===`pt-BR`?`Documentação local`:`Local documentation`}),(0,x.jsx)(`h2`,{children:e===`pt-BR`?`Ajuda e guides do framework`:`Framework help and guides`})]}),(0,x.jsx)(`button`,{"aria-label":e===`pt-BR`?`Fechar ajuda`:`Close help`,onClick:t,type:`button`,children:`×`})]}),(0,x.jsxs)(`div`,{className:`dashboard-help-layout`,children:[(0,x.jsxs)(`nav`,{"aria-label":e===`pt-BR`?`Documentos de ajuda`:`Help documents`,children:[(0,x.jsx)(`strong`,{children:e===`pt-BR`?`Visão geral`:`Overview`}),(0,x.jsx)(`button`,{className:a===`readme`?`is-active`:void 0,onClick:()=>o(`readme`),type:`button`,children:`README · ZAIP-AIOS`}),(0,x.jsx)(`strong`,{children:e===`pt-BR`?`Aprofundar no framework`:`Framework guides`}),i.map(e=>(0,x.jsx)(`button`,{className:a===e.id?`is-active`:void 0,onClick:()=>o(e.id),type:`button`,children:e.title},e.id))]}),(0,x.jsxs)(`article`,{children:[(0,x.jsxs)(`div`,{className:`dashboard-help-document-header`,children:[(0,x.jsx)(`h3`,{children:l?.title}),(0,x.jsxs)(`fieldset`,{"aria-label":e===`pt-BR`?`Visualização do documento`:`Document view`,children:[(0,x.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,x.jsx)(`button`,{"aria-pressed":s===`source`,className:s===`source`?`is-active`:void 0,onClick:()=>c(`source`),type:`button`,children:`Markdown`})]})]}),(0,x.jsx)(`div`,{className:`dashboard-help-sections`,children:j(l?.content??``,e).map(e=>(0,x.jsxs)(`section`,{children:[(0,x.jsx)(`h4`,{children:e.title}),s===`rendered`?(0,x.jsx)(w,{content:e.content}):(0,x.jsx)(`pre`,{children:e.content})]},e.title))})]})]})]})})}function w({content:e}){return A(T(e),k).map(({key:e,value:t})=>t.kind===`table`?(0,x.jsx)(`div`,{className:`dashboard-help-table-scroll`,children:(0,x.jsxs)(`table`,{children:[(0,x.jsx)(`thead`,{children:(0,x.jsx)(`tr`,{children:A(t.headers,e=>e).map(({key:e,value:t})=>(0,x.jsx)(`th`,{children:O(t)},e))})}),(0,x.jsx)(`tbody`,{children:A(t.rows,e=>e.join(``)).map(({key:e,value:t})=>(0,x.jsx)(`tr`,{children:A(t,e=>e).map(({key:e,value:t})=>(0,x.jsx)(`td`,{children:O(t)},e))},e))})]})},e):(0,x.jsx)(`pre`,{children:t.content},e))}function T(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&&E(o)){i();let r=D(a),o=[];for(e+=2;e<t.length&&t[e]?.includes(`|`);)o.push(D(t[e]??``)),e+=1;--e,n.push({kind:`table`,headers:r,rows:o});continue}r.push(a??``)}return i(),n}function E(e){return D(e).every(e=>/^:?-{3,}:?$/.test(e.replace(/\s/g,``)))}function D(e){return e.trim().replace(/^\|/,``).replace(/\|$/,``).split(`|`).map(e=>e.trim())}function O(e){return A(e.split(/(\*\*[^*]+\*\*)/g),e=>e).map(({key:e,value:t})=>t.startsWith(`**`)&&t.endsWith(`**`)?(0,x.jsx)(`strong`,{children:t.slice(2,-2)},e):(0,x.jsx)(y.Fragment,{children:t},e))}function k(e){return e.kind===`text`?`text:${e.content}`:`table:${e.headers.join(``)}:${e.rows.map(e=>e.join(``)).join(``)}`}function A(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 j(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{C as DashboardHelpDialog};