@zaip-ai/cli 1.0.8 → 1.3.0

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,72 @@
+# 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.
+
+`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.
+
+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.

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

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

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

@@ -0,0 +1,52 @@
+# Contrato de telemetria do Monitor de Custos
+
+Atualizado em 26 de julho de 2026.
+
+## Escopo
+
+O Monitor de Custos é uma visão financeira de invocações LLM. Cada linha exibida deve possuir:
+
+- tokens coletados;
+- custo BRL calculável a partir dos tokens e do catálogo histórico;
+- duração de origem observada.
+
+Runs de lifecycle não são automaticamente linhas financeiras. Uma Run sem chamada LLM, ou com chamada sem correspondência local verificável, permanece no histórico de Operação e não entra no Monitor. Isso impede que `0` seja usado para esconder falta de coleta.
+
+## Fonte e proveniência
+
+A projeção é **manifest-first**: usa os manifests e registros Git como fonte canônica e a telemetria local apenas para uma reconciliação com correspondência exata. O Dashboard não usa SQLite como fonte de dados do Monitor de Custos.
+
+Tokens, custo e duração exibidos no Monitor mantêm proveniência observada. Uma duração limitada de lifecycle com proveniência `legacy_inferred` pode permanecer em Operação e Rastreabilidade, mas não completa uma linha financeira nem entra em seus agregados.
+
+## Cobertura e valores exibidos
+
+`Cobertura de 100%` neste monitor significa que todas as linhas financeiras exibidas têm tokens, custo e duração observada. A contagem e a cobertura precisam ser recalculadas após qualquer mudança no critério de elegibilidade; não reutilize uma auditoria anterior como prova do conjunto novo.
+
+Os agregados de Conversas, Providers, Agentes, Modelos, Diário, Mensal e Anual usam as mesmas invocações financeiras da tabela. Um agente configurado sem invocações no período é um agregado vazio real e exibe zero. Duração ausente exibe `Indisponível`; o valor bruto e sua proveniência continuam disponíveis para auditoria.
+
+Não se deve converter em zero um registro que esteja fora do conjunto financeiro por ausência de coleta. Na auditoria, 126 Runs de Operação estavam nessa condição: 111 sem chamada LLM e 15 sem correspondência local única. Elas não alteram a cobertura das linhas financeiras.
+
+## Filtros e totais
+
+Filtros preenchidos somente com data são inclusivos: a data inicial começa em `00:00:00.000Z` e a final termina em `23:59:59.999Z`. O card de custo da Visão geral recebe o mesmo conjunto ativo do Monitor de Custos; por isso card, tabela e total devem coincidir para o mesmo período e moeda.
+
+## Verificação operacional
+
+1. Backfill dos manifests lifecycle após alterar records ou reconciliação:
+
+   ```powershell
+   node packages/cli/dist/index.js manifest rebuild --confirm-full-scan --json
+   ```
+
+2. Execute as validações do módulo e dos artefatos publicados:
+
+   ```powershell
+   corepack pnpm --filter @zaip-ai/dashboard-cost-monitor typecheck
+   corepack pnpm --filter @zaip-ai/dashboard-cost-monitor test -- agent-groups.test.ts CostMonitorPage.test.tsx CostTables.test.ts build-cost-monitor-projection.test.ts
+   corepack pnpm release:artifacts
+   node scripts/validate-release-parity.mjs --release
+   ```
+
+3. Consulte `/api/v2/cost-monitor` no período auditado e confirme, para cada grupo, que `missing_tokens`, `missing_cost_brl` e `missing_duration` são zero. Em seguida, compare o total de custo retornado com o card da Visão geral usando exatamente os mesmos filtros.
+
+Se houver uma lacuna, preserve-a como ausência até existir uma correspondência exata e única. Ação de reconciliação não autoriza estimar token, custo ou duração.

package/templates/.agents/zaip-aios/guides/22-fluxos-e-roteamento.md

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