@zaip-ai/cli 1.0.8 → 1.3.1

package/templates/.agents/skills/zaip-skill-sqlite-read-model/scripts/ensure-node.mjs

@@ -2,17 +2,40 @@ import { execFileSync } from "node:child_process";
 
 const minimumMajor = 22;
 function version() {
-  try { return execFileSync(process.execPath, ["--version"], { encoding: "utf8" }).trim(); } catch { return null; }
+  try {
+    return execFileSync(process.execPath, ["--version"], { encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
 }
 const current = version();
 if (current && Number.parseInt(current.slice(1), 10) >= minimumMajor) {
   process.stdout.write(`${current} is ready\n`);
   process.exit(0);
 }
-if (process.platform !== "win32") throw new Error(`Node.js ${minimumMajor}+ is required; automatic installation is only configured for Windows.`);
+if (process.platform !== "win32")
+  throw new Error(
+    `Node.js ${minimumMajor}+ is required; automatic installation is only configured for Windows.`,
+  );
 try {
-  execFileSync("winget", ["install", "--id", "OpenJS.NodeJS.LTS", "--exact", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit" });
+  execFileSync(
+    "winget",
+    [
+      "install",
+      "--id",
+      "OpenJS.NodeJS.LTS",
+      "--exact",
+      "--accept-source-agreements",
+      "--accept-package-agreements",
+    ],
+    { stdio: "inherit" },
+  );
 } catch (error) {
-  throw new Error("Node.js 22+ is missing and winget could not install the LTS release. Install Node.js manually and retry.", { cause: error });
+  throw new Error(
+    "Node.js 22+ is missing and winget could not install the LTS release. Install Node.js manually and retry.",
+    { cause: error },
+  );
 }
-process.stdout.write("Node.js LTS installation completed. Restart the terminal before running the SQLite generator.\n");
+process.stdout.write(
+  "Node.js LTS installation completed. Restart the terminal before running the SQLite generator.\n",
+);

package/templates/.agents/zaip-aios/INDEX.md

@@ -1,27 +1,62 @@
-# Indice operacional ZAIP-AIOS
+# Índice operacional ZAIP-AIOS
 
-Use esta pagina como roteador de baixo custo de tokens.
+Use esta página para localizar o guia necessário, sem carregar todo o handbook
+no contexto de cada tarefa. Os 28 guias descrevem o contrato do código-fonte;
+no projeto consumidor, confirme a versão instalada antes de aplicar comandos
+introduzidos em releases mais novas.
 
 | Necessidade | Leia |
 |---|---|
-| Comecar a usar o framework | `guides/01-primeiros-passos.md` |
-| Definir requisitos e aceite | `guides/02-requirements.md` |
-| Organizar uma entrega pequena | `guides/03-tasks.md` |
-| Planejar entrega com varias tarefas | `guides/04-specs.md` |
-| Planejar produto ou iniciativa | `guides/05-prds.md` |
-| Executar e registrar evidencias | `guides/06-execucao.md` |
-| Revisar e validar | `guides/07-revisao-e-validacao.md` |
-| Reduzir tokens e montar contexto | `guides/08-contexto-e-tokens.md` |
-| Coordenar agentes | `guides/09-agentes-e-squads.md` |
-| Tratar permissoes e segredos | `guides/10-seguranca.md` |
-| Examinar runs, custo e retrabalho | `guides/11-observabilidade-e-custos.md` |
-| Instalar, atualizar ou reverter | `guides/12-instalacao-e-upgrade.md` |
-| Aplicar praticas recomendadas | `guides/13-boas-praticas.md` |
-| Diagnosticar problemas | `guides/14-troubleshooting.md` |
-| Configurar MCPs, APIs e Codex | `guides/15-tools-e-codex.md` |
-| Entender status, Runs e reconciliação | `guides/16-lifecycle-e-reconciliacao.md` |
-| Entender tokens, precificacao e conversao de moeda | `guides/17-como-o-custo-e-calculado.md` |
-| Escolher MCP ou API | `../tools/catalog.yaml` |
+| Começar a usar o framework | [01 — Primeiros passos](guides/01-primeiros-passos.md) |
+| Definir requisitos e aceite | [02 — Requirements](guides/02-requirements.md) |
+| Organizar uma entrega pequena | [03 — Tasks](guides/03-tasks.md) |
+| Planejar entrega com várias tarefas | [04 — SPECs](guides/04-specs.md) |
+| Planejar produto ou iniciativa | [05 — PRDs](guides/05-prds.md) |
+| Executar e registrar evidências | [06 — Execução](guides/06-execucao.md) |
+| Revisar e validar | [07 — Revisão e validação](guides/07-revisao-e-validacao.md) |
+| Reduzir tokens e montar contexto | [08 — Contexto e tokens](guides/08-contexto-e-tokens.md) |
+| Coordenar agentes | [09 — Agentes e squads](guides/09-agentes-e-squads.md) |
+| Tratar permissões e segredos | [10 — Segurança](guides/10-seguranca.md) |
+| Examinar Runs, custo e retrabalho | [11 — Observabilidade e custos](guides/11-observabilidade-e-custos.md) |
+| Instalar, atualizar ou reverter | [12 — Instalação e upgrade](guides/12-instalacao-e-upgrade.md) |
+| Aplicar práticas recomendadas | [13 — Boas práticas](guides/13-boas-praticas.md) |
+| Diagnosticar problemas | [14 — Troubleshooting](guides/14-troubleshooting.md) |
+| Configurar MCPs, APIs e Codex | [15 — Tools e Codex](guides/15-tools-e-codex.md) |
+| Entender status, Runs e reconciliação | [16 — Lifecycle e reconciliação](guides/16-lifecycle-e-reconciliacao.md) |
+| Entender tokens, precificação e moeda | [17 — Como o custo é calculado](guides/17-como-o-custo-e-calculado.md) |
+| Consultar os 23 agentes | [18 — Catálogo de agentes](guides/18-catalogo-de-agentes.md) |
+| Entender assurance e autonomia | [19 — Assurance e autonomia](guides/19-assurance-e-autonomia.md) |
+| Consultar instalação detalhada | [20 — Instalação detalhada](guides/20-instalacao-detalhada.md) |
+| Consultar telemetria do Monitor | [21 — Telemetria do Monitor de Custos](guides/21-telemetria-monitor-custos.md) |
+| Entender fluxos e roteamento | [22 — Fluxos e roteamento](guides/22-fluxos-e-roteamento.md) |
+| Consultar a política de modelos | [23 — Orquestração de modelos](guides/23-orquestracao-de-modelos.md) |
+| Entender cálculo e fontes de custo | [24 — Cálculo](guides/24-calculo-de-custos-openai.md) e [25 — Fontes](guides/25-fontes-de-precos-openai.md) |
+| Consultar qualidade e release | [26 — Qualidade e release](guides/26-qualidade-e-release.md) |
+| Entender a telemetria Git-native | [27 — Telemetria Git-native](guides/27-telemetria-git-native.md) |
+| Consultar o lifecycle completo | [28 — Lifecycle completo](guides/28-lifecycle-completo.md) |
+| Escolher MCP ou API | [Catálogo de ferramentas](../tools/catalog.yaml) |
 
-Antes de agir, prevalecem `../config/project.yaml`, as Rules aplicaveis e os
-Requirements ativos. Leia records somente por ID explicito do ciclo de vida.
+## Convenções e fontes de verdade
+
+- Paths como `.agents/...` e `.local/...` partem da raiz do workspace.
+- `zaip ...` representa a CLI de lifecycle. Se não houver comando no PATH, use
+  `node .agents/runtime/bin/zaip.mjs ...` na instalação; no checkout mantenedor
+  compilado, `node packages/cli/dist/index.js ...`. O instalador público
+  `npx @zaip-ai/cli@latest init` tem outra responsabilidade.
+- `TASK-ID`, `RUN-ID`, `AC-ID`, `SHA` e outros marcadores são placeholders.
+  Substitua por identidades reais, observadas e autorizadas; não copie exemplos
+  como se fossem provas executadas.
+- Comandos de `pnpm` do repositório-fonte dependem de `package.json` e do pnpm
+  fixado em `packageManager`. Eles não estão necessariamente disponíveis em
+  projetos consumidores. Gates agregados e checks diagnósticos não precisam
+  ser executados repetidamente na mesma tentativa.
+- [Configuração](../config/project.yaml), [Rules](../rules/core.md),
+  [Requirements](../requirements/) e [catálogo de agentes](../config/agents/catalog.yaml)
+  prevalecem sobre resumos. Descubra records por manifests e abra-os por ID.
+- A [referência de prova observável](../skills/zaip-skill-change/references/observable-evidence.md)
+  governa estados, vínculos e fallback. Código, teste local, prova visual,
+  ambiente representativo, CI e produção são evidências diferentes.
+
+Guias são documentação, não certificado de release nem autorização para
+deploy, reabrir trabalho bloqueado, alterar permissões ou executar exemplos
+destrutivos. Relatórios históricos preservam o candidato e a data observados.

package/templates/.agents/zaip-aios/README.md

@@ -1,24 +1,26 @@
 # ZAIP-AIOS Handbook
 
-Este handbook e a camada operacional instalada junto do ZAIP-AIOS. Ele ajuda
+Este handbook é a camada operacional instalada junto do ZAIP-AIOS. Ele ajuda
 pessoas e agentes a localizar o procedimento certo sem carregar todo o
-framework no contexto. O contrato executavel continua nos arquivos canonicos
+framework no contexto. O contrato executável continua nos arquivos canônicos
 em `.agents/config/`, `.agents/rules/`, `.agents/requirements/` e
 `.agents/skills/`.
 
-## O que esta pasta contem
+## O que esta pasta contém
 
-- `INDEX.md`: roteador de baixo custo para os guias.
-- `guides/`: explicacoes curtas para instalacao, lifecycle, agentes, custos,
-  seguranca, contexto e ferramentas.
-- `VERSION`: versao do handbook distribuido pelo instalador.
+- [INDEX.md](INDEX.md): navegação pelos 28 guias e convenções dos comandos.
+- `guides/`: procedimentos de instalação, lifecycle, agentes, custos,
+  segurança, contexto, evidências e ferramentas.
+- [VERSION](VERSION): versão do handbook distribuído pelo instalador.
 
-O handbook nao substitui Rules, Requirements, Skills nem records do lifecycle.
-Quando houver conflito, prevalece a configuracao do projeto e a regra aplicavel.
+O handbook não substitui Rules, Requirements, skills nem records do lifecycle.
+Quando houver conflito, prevalecem a configuração do projeto e a Rule aplicável.
+Versão no checkout, pacote publicado e candidato qualificado podem diferir;
+presença de uma instrução ou screenshot não comprova execução naquele ambiente.
 
 ## Como consultar sem desperdiçar contexto
 
-1. Leia primeiro `INDEX.md` e escolha um unico guia pelo objetivo atual.
+1. Leia primeiro [INDEX.md](INDEX.md) e escolha o guia pelo objetivo atual.
 2. Leia `.agents/config/project.yaml` antes de executar trabalho: ele define se
    ZAIP esta ativo, a stack e os clientes habilitados.
 3. Para trabalho persistente, carregue `.agents/rules/core.md` e somente as
@@ -30,13 +32,22 @@ Quando houver conflito, prevalece a configuracao do projeto e a regra aplicavel.
 
 ## Mapa rapido
 
-- Comece pelo guia 01 para a primeira instalacao e pelo 12 para upgrade ou
-  rollback.
+- Comece pelo [guia 01](guides/01-primeiros-passos.md) para orientação inicial,
+  pelo [20](guides/20-instalacao-detalhada.md) para instalação detalhada e pelo
+  [12](guides/12-instalacao-e-upgrade.md) para upgrade ou rollback.
 - Use os guias 03 a 06 para Tasks, SPECs, PRDs e execucao com evidencias.
 - Use o guia 09 para delegacao entre os 23 agentes e 6 squads registrados.
 - Use o guia 16 para entender status, reconciliacao e a ordem de finalizacao.
-- Use o guia 17 para interpretar tokens, precificacao e conversao de moeda.
+- Use os guias 17 e 24 a 25 para interpretar tokens, precificacao e conversao de moeda.
+- Use os guias 18 a 28 quando precisar do contrato completo de agentes, lifecycle, telemetria, qualidade, instalacao ou roteamento.
 
 O instalador npm projeta esta pasta da `.agents` canonica para o tarball e a
 recria no projeto consumidor. Arquivos em `public-cli/packages/cli/templates`
 sao artefatos gerados do empacotamento, nao uma segunda fonte a ser editada.
+
+Para concluir trabalho, use [revisão e validação](guides/07-revisao-e-validacao.md)
+e o [contrato de prova observável](../skills/zaip-skill-change/references/observable-evidence.md).
+Registros estruturados validam vínculos, não substituem o exame do resultado.
+Consulte [qualidade e release](guides/26-qualidade-e-release.md) para distinguir
+checks locais, CI e aprovação de produção. Documentação não autoriza publicação
+nem reabertura de entregas históricas bloqueadas.

package/templates/.agents/zaip-aios/VERSION

@@ -1 +1 @@
-1.0.8
+1.3.0

package/templates/.agents/zaip-aios/guides/02-requirements.md

@@ -10,3 +10,8 @@ Use Requirement para uma obrigacao duravel e testavel.
 6. Promova somente depois de validar consistencia e rastreabilidade.
 
 Um bom criterio responde inequivocamente: passou ou falhou?
+
+Para uma entrega nova ou retomada explicitamente, planeje também o cenário
+discriminante, ambiente e modalidade de observação por AC. O contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md)
+define estados, limites e o que ainda depende de revisão humana.

package/templates/.agents/zaip-aios/guides/06-execucao.md

@@ -5,13 +5,22 @@
 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.
+6. Registre decisoes consequenciais, observações por AC, evidencias e desvios.
+7. Antes de encerrar, execute os gates finais aplicáveis, documente rollback,
+   produza o commit isolado quando houver mutação e persista Validation/Evidence
+   do candidato exato. Falta de prova permanece pendência.
+8. Depois dos demais descendentes e das provas, execute `zaip-agent-finalizer`
+   como último filho. Nenhum filho novo pode iniciar depois dele.
+9. Aplique a decisão terminal pela CLI: Task, Change e Execution; atualize os
+   manifests e finalize a Run raiz, separando status técnico e resultado da Task.
 
 Nao marque conclusao por esforco: conclua pelo resultado verificavel. Gate insuficiente ou finalizador ausente usa blocked; erro tecnico impeditivo usa failed; cancelamento exige pedido explicito.
 
+Quando a entrega requer observação, siga o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md):
+o registro descreve o resultado declarado e seus limites, mas não executa o
+procedimento nem aprova o AC sozinho.
+
 `execute` respeita o menor grão nomeado: Task executa um nó elegível; SPEC executa sua DAG; PRD executa todas as SPECs selecionadas. “Conclua a execução” ou “finalize a implementação” em trabalho ativo continua Tasks e gates, mas nunca força sucesso. “Desenvolva/melhore/aprimore” volta a planejamento/rework e exige nova promoção.
 
 ## Modelo, effort e velocidade por origem

package/templates/.agents/zaip-aios/guides/07-revisao-e-validacao.md

@@ -6,3 +6,10 @@
 4. Verifique seguranca, compatibilidade, documentacao e rollback.
 5. Classifique achados por impacto e cite evidencia concreta.
 6. Registre o resultado sem alterar implementacao em uma revisao read-only.
+
+Para ACs que exigem observação, confira cenário, expectativa, resultado,
+candidato, ambiente, locators e limitações segundo o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
+`confirmed` pode complementar uma Evidence compatível, mas não substitui
+validação, revisão independente nem finalizador. `pending`, `limited`,
+`failed` e `not_applicable` não são aprovação.

package/templates/.agents/zaip-aios/guides/10-seguranca.md

@@ -164,6 +164,29 @@ Essas camadas reduzem probabilidade e impacto, mas podem conter bugs ou lacunas.
 nativos de `zaip-aios-security` oferecem proteção adicional ao negar escrita fora do workspace
 e egress para destinos diferentes de `github.com` antes que a operação alcance o sistema ou a rede.
 
+## Proteções do candidato e limites
+
+O Dashboard é um serviço local: antes de criar a sessão ou atender rotas,
+aceita somente autoridades HTTP `localhost` e `127.0.0.1`, com porta válida.
+Hostnames arbitrários não recebem o cookie de bootstrap, mesmo que apontem
+para loopback. Isso complementa a sessão e as verificações de origem; não
+autoriza expor o serviço por proxy ou na rede pública.
+
+Na gravação de Validation, Evidence, Observation e eventos de Run, padrões
+conhecidos de credenciais são rejeitados com erro sanitizado. Isso inclui
+Bearer/Basic, chaves privadas, atribuições explícitas de senha/chave e URLs
+com credenciais ou parâmetros sensíveis. Valores sanitizados como
+`[REDACTED]` e métricas numéricas de tokens continuam aceitos. A proteção não
+é um scanner universal de segredos: sanitize o conteúdo antes de registrá-lo
+e não use o aceite do parser como prova de ausência de dados sensíveis.
+Leitura de histórico não o sanitiza nem altera retroativamente sua validade.
+
+Operações concorrentes de lock preservam a contenção física. Se uma entrada
+desaparecer durante a resolução no Windows, apenas `ENOENT` na entrada
+lógica permite subir ao pai e revalidá-lo. Symlink/junction existente fora
+da raiz e outros erros continuam bloqueando a escrita; não existe exceção
+por nome de diretório temporário do sistema.
+
 ## Escolha do perfil
 
 Use `zaip-aios-security` quando:

package/templates/.agents/zaip-aios/guides/11-observabilidade-e-custos.md

@@ -1,12 +1,12 @@
 # Observabilidade e custos
 
-1. Selecione o Run pelo ID.
-2. Verifique duracao, tokens, custo, retries e retrabalho.
-3. Compare aceite planejado com evidencia produzida.
+1. Selecione a Run pelo ID e confirme a fonte de cada métrica.
+2. Verifique duração, tokens, custo, retries e retrabalho, distinguindo observado, reconciliado e estimado.
+3. Compare aceite planejado com evidência produzida.
 4. Identifique gates lentos, contexto excessivo e chamadas repetidas.
-5. Agregue tendencias sem expor prompts ou segredos sensiveis.
+5. Agregue tendências sem expor prompts ou segredos sensíveis.
 6. Converta achados recorrentes em Rule, Requirement ou melhoria de skill.
 
-Run 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.
+Run é o envelope da chamada do `zaip-agent-orchestrator`; `parent_run_id` nulo identifica esse nível. Sub-Run é a chamada de qualquer subagente e possui `parent_run_id`. Ambas podem agregar Calls, segmentos de uso, tokens e custo; Calls não possuem tela ou lifecycle próprio. A configuração solicitada de modelo e effort pertence à Run. Modelo, effort e tier efetivos só devem ser reportados quando vierem de evento/provider observado: defaults do catálogo, seleção planejada ou comportamento aparente não os comprovam. Operação e Monitor de Custos apresentam “Chamadas do agente orquestrador” e “Chamadas de subagentes”; a Execution soma as duas categorias, finalizadores e Calls sem dupla contagem. Cada segmento de uso possui uma chave de origem e só pode ser atribuído uma vez; uma correção de duplicidade registra supersessão e preserva o evento histórico. Inspecione `run_purpose`, pai e `agent_name`; agentes do catálogo usam `zaip-agent-*`. Diferencie status técnico da chamada de agente e resultado terminal da Task. Reconcilie lifecycle globalmente apenas por comando humano explícito ou pelo popup confirmado; isso não ocorre em cada turno nem ao abrir o dashboard.
 
-A 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.
+A criação explícita de PRD/SPEC vincula a Run de definição e o `creation_run_id` ao macro. Duração, tokens e custo aparecem no PRD/SPEC antes de existirem Tasks somente quando houver fonte capturada ou derivação identificada por proveniência. Um valor `estimated`, `legacy_inferred` ou `reconciled` não é dado observado e não comprova medição da chamada. Quando duração, tokens ou custo não foram capturados, eles permanecem explicitamente indisponíveis (`null`/`unavailable`); nunca atribua telemetria ausente nem transforme ausência em zero. Pensar sem criar permanece apenas em Conversas.

package/templates/.agents/zaip-aios/guides/13-boas-praticas.md

@@ -7,6 +7,9 @@
 - Prefira configuracao explicita a convencoes ocultas.
 - Leia contexto sob demanda e preserve o budget de tokens.
 - Trate documentacao, observabilidade e rollback como parte da entrega.
+- Registre observação somente como resultado declarado e vinculado; ela não
+  executa comandos, não examina automaticamente telas e não aprova um AC.
+  Aplique o [contrato de prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
 - Nunca termine a Run raiz sem o Sub-Run finalizador ou com Task em executing/verifying.
 - Nao terminalize SPEC/PRD por causa do resultado isolado de uma Task filha.
 - Prefira reconciliacao manual sob demanda; hooks de escrita fazem checagem local sem varredura global.

package/templates/.agents/zaip-aios/guides/16-lifecycle-e-reconciliacao.md

@@ -2,7 +2,7 @@
 
 ## Entradas
 
-- Conversation: pergunta, feedback ou analise read-only; cria Run intake e nenhuma Task.
+- Conversation: pergunta, feedback ou análise read-only; captura uma interaction e Run sem Task artificial.
 - Task avulsa: resultado independente. Pedido de acao entra em Execucao antes da primeira escrita; pedido apenas de preparacao pode parar em Pronto para Executar.
 - SPEC: planejamento tecnico de multiplas Tasks; draft fica em Planejamento.
 - PRD: definicao de produto; draft fica em Definicao.
@@ -22,7 +22,7 @@ Pensar/explorar PRD ou SPEC é Conversation. Criar explicitamente persiste macro
 
 ## Execution, Runs, Sub-Runs e Calls
 
-- Execution coordena a DAG de uma ou mais Tasks.
+- Execution `interaction` registra conversa/definição; `delivery` coordena o trabalho materializado e sua DAG quando aplicável.
 - Run e a chamada raiz do `zaip-agent-orchestrator`; possui `parent_run_id` nulo.
 - Sub-Run e cada chamada de subagente; possui `parent_run_id` e compartilha o mesmo ledger `RUN-*`.
 - Novas gravacoes usam somente `run_role: intake|orchestrator|subagent`; `owner|contributor` sao valores historicos aceitos apenas na leitura e normalizados imediatamente.
@@ -30,7 +30,12 @@ Pensar/explorar PRD ou SPEC é Conversation. Criar explicitamente persiste macro
 - cada Run/Sub-Run fixa agente, modelo e effort; mudanca deliberada abre outra chamada de agente.
 - Calls e ferramentas sao eventos internos; quantidade, tokens e custo ficam agregados na Run/Sub-Run, sem tela propria.
 
-O 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.
+Toda delivery e interaction com descendentes exigem ao menos um executor
+elegível por capacidade e o `zaip-agent-finalizer` como último filho. Ele aguarda
+os demais descendentes, bloqueia novas chamadas e retorna a decisão restrita
+para a CLI aplicar. Interaction read-only sem descendentes termina após a
+resposta, sem executor/finalizador. Publicação puramente Git não cria lifecycle.
+Status técnico da chamada de agente e resultado do trabalho são independentes.
 
 `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.
 
@@ -40,6 +45,10 @@ O ultimo filho de qualquer Execution e sempre o `zaip-agent-finalizer`. Ele agua
 
 Ao 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.
 
+Observações declaradas seguem o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
+Elas não mudam status da Task nem permitem à reconciliação inferir sucesso.
+
 Novas 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.
 
 ## Reconciliacao

package/templates/.agents/zaip-aios/guides/17-como-o-custo-e-calculado.md

@@ -1,6 +1,6 @@
 # Como o custo é calculado
 
-Cada valor começa na telemetria de uma chamada LLM. O dashboard não estima uso ausente: dado indisponível continua indisponível.
+Cada estimativa de custo começa em tokens de uma chamada LLM capturados por fonte aceita. O dashboard não estima uso ausente: tokens ou custo sem os componentes necessários permanecem indisponíveis. Uma duração estimada é uma derivação identificada por proveniência e não preenche telemetria de uso.
 
 ## 1. Separe os componentes de uso
 
@@ -11,7 +11,7 @@ Cada valor começa na telemetria de uma chamada LLM. O dashboard não estima uso
 
 ## 2. Aplique as tarifas publicadas do modelo
 
-O modelo e o tier de serviço escolhidos definem a tabela de tarifas. Para uma chamada, o total em USD é:
+O modelo e o tier de serviço efetivamente observados, quando disponíveis, definem a tabela de tarifas. Para uma chamada, o total em USD é:
 
 | Componente | Cálculo |
 | --- | --- |
@@ -19,14 +19,14 @@ O modelo e o tier de serviço escolhidos definem a tabela de tarifas. Para uma c
 | Cache | `cache / 1.000.000 × tarifa de cache` |
 | Output | `output / 1.000.000 × tarifa de output` |
 
-O dashboard soma esses componentes uma única vez. Quando uma tarifa publicada não existe, ela permanece indisponível em vez de ser inventada.
+O dashboard soma esses componentes uma única vez. Quando a identidade do modelo/tier, os tokens necessários ou uma tarifa do catálogo versionado não existem, o custo permanece indisponível em vez de ser inventado.
 
 ## 3. Considere contexto, velocidade e esforço
 
-Acima do limite de contexto longo de um modelo, o multiplicador publicado de input também vale para cache e o multiplicador de output vale para todo o output. Priority/Fast usa a sua tabela de tarifas publicada, quando disponível. O multiplicador exibido é apenas uma comparação com Standard, nunca uma cobrança extra.
+Acima do limite de contexto longo de um modelo, o multiplicador publicado de input também vale para cache e o multiplicador de output vale para todo o output. `priority` usa a tabela publicada correspondente quando disponível. `fast` do Codex pode ser apresentado apenas como cenário API Priority equivalente; não prova atendimento API em Priority. O multiplicador exibido é uma comparação com Standard, nunca uma cobrança extra.
 
 O esforço não possui multiplicador direto de preço. Ele só pode aumentar o custo indiretamente quando aumenta reasoning, output ou ciclos de execução registrados.
 
 ## 4. Converta para a moeda selecionada
 
-O total da chamada é calculado primeiro em USD. Em BRL, é usada a cotação registrada no período relevante; a cotação atual é mantida separadamente para conversões atuais. Mudar a moeda de exibição nunca altera a telemetria de tokens nem o cálculo em USD.
+O total da chamada é calculado primeiro em USD. Em BRL, a estimativa exige uma cotação identificada; a cotação histórica registrada e a cotação corrente são fontes distintas. Mudar a moeda de exibição nunca altera a telemetria de tokens nem o cálculo em USD.

package/templates/.agents/zaip-aios/guides/18-catalogo-de-agentes.md

@@ -0,0 +1,76 @@
+# Catálogo de agentes
+
+`.agents/config/agents/catalog.yaml` é a única fonte canônica dos agentes ZAIP. Adapters Codex e Claude são projeções geradas: depois de qualquer alteração no catálogo, execute `node packages/cli/dist/index.js adapters build` e valide com `node packages/cli/dist/index.js adapters check --json`.
+
+## Identidade técnica e persona
+
+Cada agente possui identidade técnica estável: `id` e `codex_name`. A persona editável é `persona.nome` e `persona.cargo`, ambos em snake_case. Ela produz, sem crescimento entre invocações, o `codex_task_name` e exatamente um candidato idêntico:
+
+```text
+codex_task_name = "{nome}_{cargo}_zaip_agent"
+nickname_candidates = ["{nome}_{cargo}_zaip_agent"]
+```
+
+O schema e a API rejeitam um task name ou nickname manual, múltiplos candidatos ou valores que não sejam a derivação acima. O Dashboard omite esses campos no payload e envia somente a persona; uma edição de persona preserva a identidade técnica. Snapshots de Run usam a identidade de catálogo observada e não inventam persona.
+
+## Agentes canônicos
+
+| person | função | zaip-agent | codex_task_name | descrição resumida da função | quando chamar | quando não chamar | palavras-chave importantes para acionar agent |
+| --- | --- | --- | --- | --- | --- | --- |
+| Dave | Product Owner | `zaip-agent-orchestrator` | `dave_product_owner_zaip_agent` | Organiza a entrega, resolve a DAG e delega com menor privilégio. | Trabalho executável com mais de uma etapa ou especialista. | Implementação direta, revisão ou aprovação. | `orchestration`, `dag`, `delegation`, `lifecycle` |
+| Rafa | Tech Lead | `zaip-agent-builder` | `rafa_tech_lead_zaip_agent` | Cria/refina SPECs e executa delivery genérico, inclusive dashboard/local. | Definição técnica ou mudança sem especialista mais específico. | PRD, design central, website, frontend ou backend especializados. | `spec`, `architecture`, `decomposition`, `dashboard`, `local` |
+| Leo | Software Engineer | `zaip-agent-task-executor` | `leo_software_engineer_zaip_agent` | Executa Task genérica delimitada, inclusive dashboard/local, e produz evidência. | Task pronta, autocontida e sem escopo de especialista obrigatório. | Planejamento macro, coordenação ou revisão independente. | `task`, `implementation`, `verification`, `evidence`, `local` |
+| Bia | Product Manager | `zaip-agent-analyst` | `bia_product_manager_zaip_agent` | Cria/refina PRDs e analisa interações sem antecipar Tasks de delivery. | Problema de produto, PRD, descoberta, escopo ou refinamento. | SPEC, implementação, aprovação técnica ou deploy. | `prd`, `product`, `discovery`, `requirements`, `problem` |
+| Gui | Quality Assurance Lead | `zaip-agent-finalizer` | `gui_quality_assurance_lead_zaip_agent` | Avalia a barreira final e emite somente o resultado terminal permitido. | Obrigatoriamente como último Sub-Run de interação ou delivery. | Antes de executor/revisor terminar ou para corrigir código. | `finalization`, `terminal`, `barrier`, `task-finalizer` |
+| Nanda | Principal Engineer | `zaip-agent-reviewer` | `nanda_principal_engineer_zaip_agent` | Revisa Requirements, diff, testes e evidências sem mutar produto. | Mudança implementada que precisa de revisão independente. | Para implementar a própria correção ou integrar worktrees. | `review`, `findings`, `requirements`, `diff` |
+| Dani | Integration Engineer | `zaip-agent-integrator` | `dani_integration_engineer_zaip_agent` | Integra trabalho revisado e executa gates combinados. | Worktrees ou mudanças independentes já revisadas. | Antes da revisão ou para criar requisitos. | `integration`, `merge`, `combined-gates`, `worktree` |
+| Ana | Quality Auditor | `zaip-agent-auditor` | `ana_quality_auditor_zaip_agent` | Reproduz evidências e emite auditoria independente. | Risco alto, release ou alegação que exige reprodução final. | Implementação, correção ou autoria da evidência. | `audit`, `reproduce`, `release`, `quality` |
+| Lia | Technical Writer | `zaip-agent-writer` | `lia_technical_writer_zaip_agent` | Produz resumo fiel, análise de transcrição com timestamps e documentação grounded em fontes. | Resumo delimitado, transcrição timestampada ou documentação com fontes declaradas. | Pesquisa sem fontes, decisão de produto ou afirmações não suportadas. | `summary`, `transcript`, `timestamps`, `source-grounding`, `documentation` |
+| Gabi | Data Analyst | `zaip-agent-data-analyst` | `gabi_data_analyst_zaip_agent` | Analisa datasets delimitados com método, incerteza e reprodução. | Métricas, dados estruturados ou diagnóstico quantitativo. | Sem dados, para implementar produto ou editar dashboard. | `data`, `metrics`, `analysis`, `dataset` |
+| Tati | Refactoring Specialist | `zaip-agent-refactoring-specialist` | `tati_refactoring_specialist_zaip_agent` | Planeja e executa refactors, migrações e modularização com inventário, mapa, slices reversíveis e gates. | Refactor, migração, arquitetura, modularização ou inventário de código. | Mudança pontual sem refactor, UI central de design ou deploy. | `refactor`, `migration`, `modularization`, `inventory`, `refactor-map`, `rollback` |
+| Doug | Frontend Specialist | `zaip-agent-frontend` | `doug_frontend_specialist_zaip_agent` | Implementa somente `apps/frontend/**`, acessibilidade e integração conforme `DESIGN.md`. | `apps/frontend/**` ou capability explícita de frontend. | Dashboard/local, website institucional, backend ou regra central de design. | `frontend`, `ui`, `accessibility`, `visual-contract` |
+| Will | Backend Specialist | `zaip-agent-backend` | `will_backend_specialist_zaip_agent` | Implementa backend, APIs, persistência e integrações. | `apps/backend/**`, `modules/**` ou capability de backend. | Frontend, website ou design visual central. | `backend`, `api`, `persistence`, `integration` |
+| Jonny | Website Developer | `zaip-agent-website-developer` | `jonny_website_developer_zaip_agent` | Cria sites/LPs com stack do framework, SEO, GEO e acesso por agentes. | `apps/site/**`, site institucional, LP, SEO, GEO ou Markdown for Agents. | App de produto, backend ou mudança da regra central de design. | `website`, `landing-page`, `seo`, `geo`, `markdown-for-agents`, `agent-readiness` |
+| Manu | Product Designer | `zaip-agent-designer` | `manu_product_designer_zaip_agent` | Governa `DESIGN.md`, design tokens (cor, tipografia, espaçamento e raio), componentes centrais e páginas de catálogo digital. | Regra central de design, Design System, tokens, `design-system` ou `componentes`. | Word, PPT, imagem de marketing ou componente local que apenas consome regras existentes. | `design-system`, `design.md`, `tokens`, `central-components`, `componentes` |
+
+| Dan | Cloud Engineer | `zaip-agent-cloud-engineer` | `dan_cloud_engineer_zaip_agent` | Projeta e valida infraestrutura cloud declarada. | Infraestrutura cloud, provisionamento, containers, Terraform ou Docker. | Implementação de aplicação, deploy ou infraestrutura fora do escopo declarado. | `cloud`, `terraform`, `docker`, `provisioning` |
+| Luiz | Security Auditor | `zaip-agent-security-auditor` | `luiz_security_auditor_zaip_agent` | Audita segurança de forma independente e somente leitura. | Auditoria de segurança, mudança sensível ou release que exige avaliação independente. | Implementação, autoria de remediação ou deploy. | `security`, `audit`, `risk`, `release` |
+| Lucia | Marketing Analyst | `zaip-agent-marketing-analyst` | `lucia_marketing_analyst_zaip_agent` | Planeja marketing, copy, campanhas e briefs de imagem com evidência. | Estratégia de marketing, campanha, copy de landing page ou brief de imagem. | Implementação de produto, backend ou governança central de design. | `marketing`, `copy`, `campaign`, `image-brief` |
+| Sarah | Branding Specialist | `zaip-agent-brand-strategist` | `sarah_branding_specialist_zaip_agent` | Define e governa plataforma de marca, Brandbook, posicionamento, arquétipos, diferencial semântico e arquitetura de marca com evidências. | Estratégia ou governança de marca, Brandbook, posicionamento, arquétipos, arquitetura de marca ou consistência de identidade como decisão principal. | Aplicação rotineira de marca aprovada, campanha, script comercial, análise quantitativa bruta ou documento geral sem decisão de marca. | `branding`, `brandbook`, `positioning`, `archetypes`, `semantic-differential`, `brand-architecture` |
+| Robert | Growth Strategist | `zaip-agent-growth-strategist` | `robert_growth_strategist_zaip_agent` | Orienta estratégia de crescimento, RevOps, experimentos, receita, custos e recomendações executivas baseadas em dados. | Estratégia de negócio, Growth, RevOps, modelo de negócio, priorização de portfólio ou impacto financeiro como decisão principal. | Campanha ou conteúdo, Brandbook, playbook comercial, validação quantitativa bruta ou ato comercial externo. | `growth`, `revops`, `experimentation`, `revenue`, `cost-optimization`, `business-strategy` |
+| Aaron | Sales Specialist | `zaip-agent-sales-specialist` | `aaron_sales_specialist_zaip_agent` | Cria processos, playbooks, qualificação, scripts, enablement e handoffs comerciais internos. | Metodologia comercial, qualificação, negociação preparada, processo SDR/closer, script, playbook ou handoff de pipeline. | Estratégia de Growth/RevOps, campanha ou copy de marketing, governança de marca, análise bruta de dados, política jurídica ou ato comercial externo. | `sales`, `qualification`, `sales-playbook`, `sales-script`, `sdr`, `closer`, `pipeline-handoff` |
+| Clara | Operations Generalist | `zaip-agent-general-operations` | `clara_operations_generalist_zaip_agent` | Executa artefatos operacionais delimitados fora de escopos especialistas: documentos, apresentações, planilhas, processos e comparativos. | Documento, apresentação, planilha, processo ou pesquisa comparativa sem capability especialista obrigatória. | Produto, design-system, marketing, dados, segurança, cloud, jurídico vinculante ou ato externo. | `operations`, `document`, `presentation`, `spreadsheet`, `process`, `comparison` |
+| Renata | Governance Compliance Specialist | `zaip-agent-governance-compliance` | `renata_governance_compliance_specialist_zaip_agent` | Prepara artefatos internos não vinculantes de RH, jurídico operacional, política, privacidade, fornecedores e risco. | Minuta, checklist, matriz de risco ou pacote interno de aprovação sem ato externo. | Parecer jurídico vinculante, assinatura, representação, protocolo, contratação ou decisão humana. | `governance`, `compliance`, `hr`, `legal-operations`, `privacy`, `vendor`, `risk` |
+
+## Squads organizacionais
+
+O catálogo contém 23 agentes agrupados visualmente em seis squads: **Product** (3), **Admin & Operations** (3), **Development** (6), **Delivery Assurance** (4), **Infra & Security** (2) e **Growth — Sales, Marketing and Branding** (5). A soma é 23.
+
+Os squads facilitam a leitura organizacional e a colaboração humana. Eles não são uma fonte de roteamento: `selectAgentForWork` continua a escolher o agente exclusivamente pelas capabilities mandatórias, escopos explícitos, prioridade e ID; cada agente conserva seus write scopes e permissões.
+
+## Roteamento determinístico
+
+`selectAgentForWork` deriva uma capacidade mandatória a partir de escopos explícitos antes de aplicar a seleção ordenada por prioridade e ID.
+
+- `.agents/design/*`, `.agents/design/**`, `DESIGN.md`, `tokens.json`, `apps/catalog/**` ou capability explícita de Design System/tokens/componentes/páginas seleciona Manu. Manu é a regra visual central; Doug somente a consome em `apps/frontend/**`.
+- `apps/site/**` ou capability explícita `website-delivery`, SEO, GEO, Markdown for Agents ou Agent Readiness seleciona Jonny.
+- `apps/frontend/**` seleciona Doug quando a capability é frontend; `apps/backend/**` e `modules/**` selecionam Will quando a capability é backend.
+- Capabilities de governança, RH, jurídico operacional, políticas, privacidade, fornecedores ou riscos selecionam Renata. Ela prepara o pacote revisável e a ação humana necessária, mas não executa ato vinculante ou externo.
+- Capabilities de plataforma ou governança de marca, Brandbook, posicionamento, arquitetura de marca, arquétipos ou diferencial semântico selecionam Sarah. Ela governa a identidade e encaminha aplicação de design system para Manu e ativação de marketing para Lucia.
+- Capabilities de estratégia de Growth, RevOps, experimentação, receita, custo, funil, unit economics ou recomendação executiva selecionam Robert. Dados quantitativos delimitados continuam com Gabi, e processos comerciais internos com Aaron.
+- Capabilities de metodologia comercial, qualificação, playbooks, scripts, SDR, closer ou handoff de pipeline selecionam Aaron. Ele não realiza ato comercial externo nem substitui Sarah, Lucia, Robert ou Gabi em suas fronteiras especializadas.
+- Capabilities de documentos, apresentações, planilhas, processos e comparativos — ou trabalho delimitado sem capability explícita e sem escopo obrigatório — selecionam Clara como fallback operacional contínuo.
+- Um diretório chamado `components` fora dos alvos canônicos não aciona Manu. O orquestrador usa a capability solicitada e os write scopes da Task.
+- `.agents/dashboard/**` e `.local/**` não selecionam Doug nem Manu: permanecem com Rafa ou Leo até que a Task declare um escopo obrigatório; artefatos operacionais não técnicos podem selecionar Clara.
+
+O orquestrador mantém a Run raiz e cada Run delegada separadas na observabilidade. Duração, tokens e custo só são agregados quando observados ou reconciliados; ausência continua indisponível, nunca zero.
+
+O dispatch autônomo passa os `Task.write_scopes` a essa seleção **por Task** e persiste o builder escolhido na entrada de cada Task. Assim uma DAG com frontend e backend usa Doug e Will nas respectivas invocações, sem transformar a seleção de uma Task em builder global. A seleção é determinística, mas não concede autoridade: o agente ainda precisa respeitar seus write scopes e permissões do catálogo.
+
+O `budget.soft_cycles` também acompanha o agente selecionado por Task e governa seu checkpoint suave. Tokens continuam observados para telemetria e custo, mas não interrompem nem exigem checkpoint. Para comparar agentes, use `zaip run aggregate --agent agent-ID`; o resultado inclui duração coberta, ciclos de uso observados, tokens, custo, cobertura e Runs de rework.
+
+Nanda (`agent-reviewer`) usa `gpt-5.6-terra` com esforço `medium` e `soft_cycles: 12`, proporcional à revisão standard. Ana (`agent-auditor`) permanece `gpt-5.6-sol`/`high` para auditoria crítica ou explicitamente auditável; Luiz (`agent-security-auditor`) permanece `gpt-5.6-sol`/`high` para auditoria de segurança explícita.
+
+## Dashboard e segurança operacional
+
+A tela **Configurações > Catálogo de agentes** apresenta a persona e mantém a identidade técnica somente leitura. Ao salvar, o runtime valida o catálogo, deriva o único nickname, sincroniza adapters e reverte a escrita se a paridade falhar. Agentes de framework permitem alteração de persona e preferências de modelo/effort; propósito, capacidades e identidade técnica continuam protegidos.

package/templates/.agents/zaip-aios/guides/19-assurance-e-autonomia.md

@@ -0,0 +1,95 @@
+# Assurance adaptativa e autonomia opt-in
+
+O ZAIP-AIOS separa duas decisões que não devem ser confundidas: quanto de prova uma entrega exige e quem executa a DAG. A primeira é governada por `assurance`; a segunda por `execution`. O modo manual continua sendo o padrão seguro e econômico.
+
+## Matriz de validação
+
+| Origem e risco | Validações aprovadas | Evidences aprovadas | Controles adicionais |
+| --- | ---: | ---: | --- |
+| Task standalone `lite` | 1 ou mais; normalmente 1 | 1 ou mais; normalmente 1 | cobertura completa dos ACs; provas extras legítimas são aceitas |
+| Task standalone `standard`, base | 2 ou mais | 1 ou mais, com pelo menos 1 Evidence consolidada | modalidades distintas; inclui teste |
+| Task standalone `standard`, elevado | 3 ou mais | 1 ou mais, com pelo menos 1 Evidence consolidada | modalidades distintas; inclui teste |
+| Task standalone `critical` | 3 ou mais | 1 dedicada por AC quando o sinal persistido exigir | teste, quality review independente e controles dirigidos pelos sinais |
+| Entrega de SPEC | 3 ou mais parentais | 3 ou mais parentais | matriz de AC, integração, spec review, quality review e commit final |
+| Entrega de PRD | 3 ou mais parentais | 3 ou mais parentais | matriz de AC/outcome, cross-SPEC E2E, spec review, quality review e commit final |
+
+Uma única Evidence pode cobrir vários ACs nos perfis `lite` e `standard`, e nos perfis parentais que não exigem Evidence dedicada por AC. Em todos os casos, a cobertura precisa ser completa e a Evidence deve referenciar uma validação tipada aprovada da mesma Task, Change e Execution. Texto declarando que algo passou não é prova.
+
+## Observação por AC
+
+Para entrega nova ou verificação retomada, use o contrato de
+[prova observável](../../skills/zaip-skill-change/references/observable-evidence.md).
+Uma observação descreve o cenário, expectativa, resultado, ambiente,
+candidato, locators e limitações. O CLI valida estrutura e vínculos, mas não
+executa o comando declarado, não examina pixels e não consulta banco
+automaticamente. Só observação `confirmed` e compatível pode complementar uma
+Evidence; nunca a aprova isoladamente. Históricos V2 sem observações continuam
+legíveis e não são promovidos retroativamente.
+
+Conteúdo de novos registros passa também por rejeição de padrões conhecidos
+de credenciais, sem ecoar valores no erro. Isso não valida a autenticidade
+da observação nem substitui sanitização e revisão humana dos locators.
+
+`standard_depth: auto` escolhe o perfil base quando `verification_scope: scoped` está persistido e o elevado para escopo mais amplo. Para registros históricos sem esse sinal, o fallback conservador usa mais de um write scope; ele não substitui a classificação nova. O perfil `lite` não é permitido como atalho para segurança, migração, irreversibilidade ou mudança multi-domínio crítica.
+
+Em `critical`, a revisão de qualidade independente é sempre exigida. Mutação é exigida apenas para segurança ou dados críticos; rollback para migração, irreversibilidade ou rollback não trivial; e Evidence por AC para segurança ou migração. Evidência de commit final é exigida para impacto em produção, ação externa ou migração. Esses controles são decididos pelos sinais de risco persistidos, não por quotas máximas de artefatos.
+
+## Ativação segura
+
+Configuração recomendada para uso normal:
+
+```yaml
+execution:
+  runtime: manual
+assurance:
+  version: 1
+  standard_depth: auto
+  require_final_commit: true
+```
+
+`require_final_commit: true` impede que validações antigas ou feitas antes da integração comprovem o candidato atual. Durante uma migração controlada do próprio framework, ele pode ser temporariamente `false`, mas a exceção precisa ser explícita e não qualifica cleanroom ou release.
+
+## Runtime autônomo
+
+Autonomia exige configuração explícita:
+
+```yaml
+execution:
+  runtime: autonomous
+  autonomous:
+    provider: codex
+    model: MODELO-PERMITIDO
+    max_parallelism: 3
+    lease_ms: 900000
+```
+
+O projeto ZAIP-AIOS limita a concorrência produtiva a `max_parallelism: 3`, mas inicia em 1. A elevação só ocorre quando existem ramos sem dependência e sem sobreposição de write scope; o coordenador reivindica cada lote novamente com os locks do scheduler. O paralelismo efetivo é sempre o menor limite entre projeto, plano independente, provider e squad. `budget.soft_cycles` é aplicado ao agente escolhido em cada Task; tokens permanecem telemetria e custo, não checkpoint. `zaip run aggregate --agent agent-ID` filtra a identidade e retorna duração, ciclos observados, tokens, custo, cobertura e rework. Telemetria não capturada permanece indisponível, nunca zero.
+
+O runtime cria Executions-filhas determinísticas somente para SPECs com dependências internas e write scopes globalmente disjuntos. Cada filha possui coordinator, estado, quota de orçamento e handoff próprios, mas todas compartilham a fila limitada pelo paralelismo efetivo e o ledger de invocações do PRD. A filha termina antes do fan-in e o pai não reexecuta suas Tasks. A Execution do PRD integra os commits das filhas, executa as modalidades parentais sobre o commit combinado e bloqueia o finalizer enquanto houver filha ativa. SPECs inelegíveis continuam na DAG global, preservando locks, orçamento e segurança do coordenador.
+
+O driver autônomo:
+
+- usa protocolo nativo JSONL de Codex ou Claude, sem shell;
+- cria worktree Git por Task a partir de uma raiz limpa;
+- limita alterações aos write scopes;
+- exige commit final e valida os artefatos tipados dentro da worktree;
+- aborta merge conflitante e não deixa merge parcial;
+- persiste estado com compare-and-swap;
+- serializa somente transições do estado durável e rebaseia cada Task, permitindo que invocações de ramos independentes executem em paralelo com segurança;
+- mantém checkpoints opacos somente em `.local`;
+- limita `lite` a uma tentativa e `standard`/`critical` a no máximo três tentativas de desenvolvimento ou reparo;
+- usa verificador independente para critical, SPEC e PRD.
+
+Na Task autônoma, o adapter respeita o mesmo rigor calculado: `lite` não exige
+um teste quando a política permite outra modalidade; mutação e rollback
+exigidos precisam de provas tipadas, inclusive em Task crítica sem pai.
+Sinais de risco ausentes mantêm o fallback conservador. Artefatos históricos
+de outra Run ou candidato não aprovam a entrega atual nem impedem uma nova
+aprovação quando as provas atuais estão completas. Limites de invocação são
+reservados atomicamente e retomadas não zeram o consumo acumulado.
+
+Ativar `autonomous` não afirma que o runtime está validado em produção. A maturidade só avança quando o mesmo hash do candidato passa validação local, cleanroom, ambiente representativo e observação de produção, nessa ordem.
+
+## Cobertura e release
+
+O ratchet de cobertura nunca reduz o piso: 80% para lines, functions e statements e 75% para branches. Uma medição atual abaixo disso pode ser registrada como baseline observada para diagnóstico, mas o gate continua vermelho. Release crítica também exige unit, E2E, arquitetura, CQRS, módulos, profile, segurança, testes negativos, paridade da distribuição e cleanroom do candidato exato.