@zaip-ai/cli 1.0.7 → 1.3.0

package/templates/.agents/skills/zaip-skill-sqlite-read-model/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: zaip-skill-sqlite-read-model
+description: Install the Node.js prerequisite and create, incrementally update, validate, or rebuild the disposable SQLite read model from canonical ZAIP records.
+---
+
+# SQLite read model
+
+Use this skill when installing, refreshing, or rebuilding the disposable SQLite
+read model. The canonical inputs are `.agents/records` and `.agents/config`;
+never load lifecycle overviews, dashboard projections, or other aggregates as
+an input.
+
+## Prerequisite and rebuild
+
+1. Confirm Node.js 22 or newer with `node --version`. If it is absent, install
+   the LTS release with `winget install --id OpenJS.NodeJS.LTS --exact` and
+   restart the terminal if `node` is still not on `PATH`.
+2. Rebuild the local runtime before rebuilding SQLite. The rebuild script imports
+   `packages/local-runtime/dist/server.cjs`; using an old bundle can create an
+   old schema even when `src/sqlite-read-model.ts` is current.
+3. Prefer the normal incremental refresh on dashboard startup. Do a full rebuild
+   after any schema/view/index change or when validation detects drift.
+4. Keep database files under `.local` (or another disposable local path),
+   untracked. Do not make DBeaver or a SQLite server a dependency.
+
+```powershell
+node .agents/dashboard/packages/local-runtime/scripts/build-sqlite-runtime.mjs
+node .agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs
+```
+
+If Windows reports `EPERM` or `EBUSY` replacing
+`.local/dashboard-sqlite/read-model.sqlite`, a live dashboard owns that file.
+Do not treat its old schema as validation evidence. Rebuild and validate an
+isolated generation instead:
+
+```powershell
+$env:ZAIP_SQLITE_DB_PATH = (Join-Path $PWD '.local/dashboard-sqlite/read-model-verify.sqlite')
+node .agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs
+node .agents/dashboard/packages/local-runtime/scripts/validate-sqlite-read-model.mjs
+```
+
+Clear `ZAIP_SQLITE_DB_PATH` after the isolated check when the shell will start
+the normal dashboard again.
+
+## Current persisted schema and objective verification
+
+The current generator (`packages/local-runtime/src/sqlite-read-model.ts`) owns
+the schema. At schema version 60 it persists exactly these tables:
+
+- `zaip_aios_activities`
+- `zaip_dim_zaip_agent`
+- `zaip_dim_llm_model`
+- `zaip_dim_provider`
+- `cost_invocation_dimension_facts`
+
+Temporary staging tables and compatibility aliases are connection-local and are
+not persisted. Persisted views use exactly one `zaip_vw_` prefix; query them
+through the documented runtime view names rather than creating duplicate
+unprefixed objects. The generator also requires the activity, cost-dimension,
+and unique run indexes listed below.
+
+After every full rebuild, run this check against the same database generation.
+It verifies database integrity, the exact table inventory, view namespace and
+compilability, and the required indexes. It exits non-zero on drift.
+
+```powershell
+@'
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { resolve } from 'node:path';
+
+const databasePath = process.env.ZAIP_SQLITE_DB_PATH ?? resolve('.local/dashboard-sqlite/read-model.sqlite');
+const database = new DatabaseSync(databasePath, { readOnly: true });
+try {
+  assert.equal(database.prepare('PRAGMA integrity_check').get().integrity_check, 'ok');
+  const objects = database.prepare("SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'").all();
+  const tables = objects.filter(({ type }) => type === 'table').map(({ name }) => name).sort();
+  assert.deepEqual(tables, ['cost_invocation_dimension_facts', 'zaip_aios_activities', 'zaip_dim_llm_model', 'zaip_dim_provider', 'zaip_dim_zaip_agent']);
+  const views = objects.filter(({ type }) => type === 'view').map(({ name }) => name);
+  assert.ok(views.length > 0, 'no persisted views');
+  assert.ok(views.every((name) => name.startsWith('zaip_vw_') && !name.startsWith('zaip_vw_vw_')), 'invalid persisted-view prefix');
+  for (const name of views) database.prepare(`SELECT * FROM main."${name.replaceAll('"', '""')}" LIMIT 0`).all();
+  const indexes = new Set(database.prepare("SELECT name FROM sqlite_master WHERE type='index'").all().map(({ name }) => name));
+  for (const name of ['zaip_activities_agent_run', 'zaip_activities_task_day', 'zaip_activities_spec_day', 'zaip_activities_prd_day', 'zaip_activities_run_id', 'zaip_activities_period_invocation', 'cost_dimension_facts_day_model', 'cost_dimension_facts_day_provider', 'cost_dimension_facts_invocation']) assert.ok(indexes.has(name), `missing index ${name}`);
+  console.log(JSON.stringify({ databasePath, tableCount: tables.length, viewCount: views.length, requiredIndexCount: 9 }));
+} finally {
+  database.close();
+}
+'@ | node --input-type=module
+```
+
+The checked-in `validate-sqlite-read-model.mjs` and
+`test-sqlite-read-model.mjs` are the installation gates for schema 60. They
+assert the five persisted tables, the `zaip_vw_` view namespace and required
+indexes against a freshly rebuilt database. Do not use an old database or
+weaken those assertions to hide a schema mismatch.

package/templates/.agents/skills/zaip-skill-sqlite-read-model/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP SQLite Read Model"
+  short_description: "Refresh the disposable SQLite dashboard read model."
+  default_prompt: "Use $zaip-skill-sqlite-read-model to prepare or refresh the SQLite read model from canonical ZAIP records."

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

@@ -0,0 +1,41 @@
+import { execFileSync } from "node:child_process";
+
+const minimumMajor = 22;
+function version() {
+  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.`,
+  );
+try {
+  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 },
+  );
+}
+process.stdout.write(
+  "Node.js LTS installation completed. Restart the terminal before running the SQLite generator.\n",
+);

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

@@ -20,6 +20,17 @@ Use esta pagina como roteador de baixo custo de tokens.
 | 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` |
+| Consultar o catálogo completo de agentes | `guides/18-catalogo-de-agentes.md` |
+| Entender assurance e autonomia | `guides/19-assurance-e-autonomia.md` |
+| Consultar instalação detalhada | `guides/20-instalacao-detalhada.md` |
+| Consultar telemetria do Monitor de Custos | `guides/21-telemetria-monitor-custos.md` |
+| Entender fluxos e roteamento | `guides/22-fluxos-e-roteamento.md` |
+| Consultar a política de modelos | `guides/23-orquestracao-de-modelos.md` |
+| Entender cálculo e fontes de custo OpenAI | `guides/24-calculo-de-custos-openai.md` e `guides/25-fontes-de-precos-openai.md` |
+| Consultar qualidade e release | `guides/26-qualidade-e-release.md` |
+| Entender a telemetria Git-native | `guides/27-telemetria-git-native.md` |
+| Consultar o lifecycle completo | `guides/28-lifecycle-completo.md` |
 | Escolher MCP ou API | `../tools/catalog.yaml` |
 
 Antes de agir, prevalecem `../config/project.yaml`, as Rules aplicaveis e os

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

@@ -1,13 +1,43 @@
 # ZAIP-AIOS Handbook
 
-Documentacao operacional local do ZAIP-AIOS para pessoas e agentes.
+Este handbook e 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
+em `.agents/config/`, `.agents/rules/`, `.agents/requirements/` e
+`.agents/skills/`.
 
-## Leitura eficiente
+## O que esta pasta contem
 
-1. Leia primeiro apenas `INDEX.md`.
-2. Abra somente o guia relacionado ao trabalho atual.
-3. Para integracoes, consulte `.agents/tools/catalog.yaml` e depois um unico manifesto.
-4. Nao carregue toda esta pasta no contexto.
+- `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.
 
-`VERSION` informa a versao do handbook instalada. As regras canonicas continuam em
-`.agents/rules/`; este handbook explica como aplica-las, mas nao as substitui.
+O handbook nao substitui Rules, Requirements, Skills nem records do lifecycle.
+Quando houver conflito, prevalece a configuracao do projeto e a regra aplicavel.
+
+## Como consultar sem desperdiçar contexto
+
+1. Leia primeiro `INDEX.md` e escolha um unico 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
+   Rules, Requirements e Skills relacionadas ao escopo.
+4. Para MCPs e integracoes, abra `.agents/tools/catalog.yaml` e depois apenas o
+   manifesto da ferramenta escolhida.
+5. Leia records de lifecycle apenas por ID explicito; historico geral nao e
+   contexto de descoberta.
+
+## Mapa rapido
+
+- Comece pelo guia 01 para a primeira instalacao e pelo 12 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 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.

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

@@ -1 +1 @@
-1.0.0
+1.3.0

package/templates/.agents/zaip-aios/guides/09-agentes-e-squads.md

@@ -1,8 +1,45 @@
 # Agentes e squads
 
-1. Delegue apenas subtarefas concretas e independentes.
-2. Dê a cada agente objetivo, limites, entradas e formato de saida.
-3. Evite dois agentes editando os mesmos arquivos.
-4. Centralize decisoes arquiteturais e integracao no agente responsavel.
-5. Exija evidencias, nao apenas declaracoes de conclusao.
-6. Use paralelismo somente quando reduzir caminho critico sem aumentar conflito.
+O catalogo em `.agents/config/agents/catalog.yaml` e a fonte canonica para
+delegacao. Ele registra 23 agentes e 6 squads. Nomes exibidos, perfis e
+capacidades podem mudar; antes de delegar, consulte o registro atual em vez de
+memorizar uma lista ou inventar uma identidade.
+
+## Como escolher
+
+1. Quebre o trabalho em subtarefas concretas, independentes e verificaveis.
+2. Escolha pelo conjunto de `capabilities`, `execution_eligibility`, ferramentas
+   e `write_scopes` do catalogo, nao apenas pelo titulo do agente.
+3. Use apenas o `codex_name` e o `codex_task_name` exatos do registro. Nao use
+   `default`, `worker`, `explorer` ou nomes ad-hoc.
+4. Defina objetivo, escopo de escrita, entradas, criterio de aceite e formato de
+   retorno antes da delegacao.
+5. Nao atribua a dois agentes arquivos ou responsabilidades que conflitem.
+
+## Squads
+
+As seis squads coordenam contextos recorrentes: entrega critica, analise de
+produto, design e website, marca e marketing, growth e RevOps, e vendas e
+governanca. A squad e um roteador de capacidade; a delegacao continua usando o
+agente catalogado que satisfaz o trabalho concreto.
+
+## Execucao e fechamento
+
+Uma Execution de delivery precisa de ao menos um executor elegivel. O
+orquestrador coordena a DAG, preserva a separacao de telemetria entre raiz e
+Sub-Runs e captura metadados observados apos spawn e termino. Reviewer,
+auditor ou integrador so entram quando sua capacidade for necessaria.
+
+O ultimo filho e sempre `zaip-agent-finalizer`, depois que os demais
+descendentes terminaram. Ele nao reescreve evidencia: aplica uma decisao
+restrita baseada em testes, diffs e registros reais. O resultado so deve ser
+reportado apos a barreira de finalizacao estar satisfeita.
+
+## Boas praticas
+
+- Centralize decisoes arquiteturais e integracao no responsavel adequado.
+- Exija caminhos de evidencia e resultados de comandos, nao declaracoes de
+  conclusao.
+- Use paralelismo apenas quando reduzir o caminho critico sem elevar conflito.
+- Escale bloqueios de autoridade, credencial, seguranca ou escopo; nao suponha
+  permissao externa.

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

@@ -6,13 +6,21 @@ O ZAIP-AIOS oferece dois perfis atuais:
 
 | Perfil | Filesystem nativo | Rede de comandos | Uso recomendado |
 | --- | --- | --- | --- |
-| `zaip-aios-security` | Escrita na raiz física do repositório, incluindo `.git`, `.agents`, `.codex` e demais arquivos ocultos | Limitada a `github.com` | Trabalho normal e princípio de menor privilégio, incluindo deploy GitHub autorizado |
-| `zaip-aios-full-access` | Escrita em `C:\` inteiro no Windows, quando as permissões do sistema permitirem | Completa, todos os domínios | Correção de configuração, diagnóstico ou operação que realmente exija acesso fora do workspace |
+| `zaip-aios-full-access` | Escrita em `C:\` inteiro no Windows, quando as permissões do sistema permitirem | Completa, todos os domínios | Default humano; evita prompt técnico do Codex para comandos, mas não cria autoridade para ações externas, destrutivas ou de publicação |
+| `zaip-aios-security` | Escrita na raiz física do repositório, incluindo `.git`, `.agents`, `.codex` e demais arquivos ocultos | Limitada a `github.com` | Opt-in de menor privilégio; reinicie o Codex após selecionar |
 
 A permissão nativa determina o que o processo tecnicamente consegue alcançar. Ela não
 substitui autorização do usuário, regras do repositório, hooks, skills ou controles do
 sistema operacional.
 
+`approval_policy = "never"` remove a confirmação técnica prévia do Codex para a
+execução de comandos dentro do perfil. Isso não é uma autorização de negócio ou
+de escopo: deploy, push/publicação, ações remotas, gastos, exclusões relevantes
+e mudanças fora do objetivo continuam exigindo pedido explícito do usuário no
+turno atual. Apps e MCPs podem manter seu próprio
+`default_tools_approval_mode = "approve"`; esse ajuste é independente da
+política de aprovação de comandos.
+
 ## `zaip-aios-security`
 
 ### Acesso concedido
@@ -70,7 +78,11 @@ pelo sandbox nativo:
 - o impacto máximo de uma edição comum fica contido no repositório;
 - todas as camadas ZAIP descritas abaixo continuam ativas.
 
-Esse perfil deve ser o padrão para desenvolvimento, revisão, testes, manutenção normal e deploy GitHub autorizado quando a escrita na identidade SSH local for necessária. A escrita em `~/.ssh` e o egress para `github.com` ampliam o impacto potencial; nunca altere chaves, credenciais ou remotos sem autorização explícita.
+Esse perfil é a opção de menor privilégio recomendada quando o trabalho cabe no workspace,
+especialmente para revisão, testes e manutenção delimitada. O perfil humano continua sendo
+`zaip-aios-full-access`; selecione `zaip-aios-security` explicitamente quando desejar contenção
+nativa. A escrita em `~/.ssh` e o egress para `github.com` ampliam o impacto potencial; nunca
+altere chaves, credenciais ou remotos sem autorização explícita.
 
 ## `zaip-aios-full-access`
 
@@ -118,8 +130,10 @@ conteúdo malicioso, dependência comprometida ou erro de escopo pode tentar:
 - enviar dados pela rede;
 - ampliar o impacto de uma falha de supply chain.
 
-Ele deve ser ativado somente quando o perfil restrito não consegue executar uma operação
-legítima e explicitamente autorizada. Após a correção, volte para `zaip-aios-security`.
+Ele é o default humano de permissão nativa. `approval_policy = "never"` evita
+prompt técnico para comandos, mas não substitui autorização explícita para
+operações externas, destrutivas ou de publicação. O hook complementar permanece
+default-deny para operações externas e não torna este perfil equivalente ao restrito.
 
 ## Camadas que reduzem o risco do full access
 
@@ -130,7 +144,7 @@ O acesso completo é mitigado por defesa em profundidade, mas nenhuma camada tor
    gasto e mutações remotas exigem pedido explícito no turno atual.
 2. **Escopo do repositório:** `AGENTS.md`, Rules e skills limitam o trabalho ao objetivo e
    proíbem inferir autoridade adicional a partir do acesso técnico.
-3. **Hook `PreToolUse`:** valida comandos e patches antes da execução; bloqueia escapes do
+3. **Hook `PreToolUse` ativo nos dois perfis:** valida comandos e patches antes da execução; bloqueia escapes do
    repositório, referências diretas a segredos, elevação, persistência de sistema, firewall,
    antivírus, serviços, Git destrutivo, banco destrutivo e clientes remotos não autorizados.
 4. **Regras `forbidden`:** arquivos em `.codex/rules/` negam classes perigosas de comandos
@@ -159,7 +173,7 @@ Use `zaip-aios-security` quando:
 - comandos precisam, no máximo, alcançar `github.com` para operações Git/SSH autorizadas;
 - menor privilégio é desejado.
 
-Use `zaip-aios-full-access` apenas quando:
+Use `zaip-aios-full-access` como default humano quando:
 
 - for necessário corrigir a própria configuração de permissões;
 - uma operação autorizada precisar de um caminho fora do workspace;

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

@@ -0,0 +1,32 @@
+# 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.
+
+## 1. Separe os componentes de uso
+
+- **Tokens de input** incluem instruções, histórico, contexto, ferramentas e a mensagem atual.
+- **Tokens de cache** fazem parte do input, não são uma quantidade extra. Eles são subtraídos do input antes da aplicação da sua própria tarifa.
+- **Tokens de output** são tudo que o modelo gerou.
+- **Tokens de reasoning** fazem parte do output. O output é cobrado uma única vez, então reasoning não cria uma segunda cobrança.
+
+## 2. Aplique as tarifas publicadas do modelo
+
+O modelo e o tier de serviço escolhidos definem a tabela de tarifas. Para uma chamada, o total em USD é:
+
+| Componente | Cálculo |
+| --- | --- |
+| Input faturável | `(input - cache) / 1.000.000 × tarifa de input` |
+| Cache | `cache / 1.000.000 × tarifa de cache` |
+| Output | `output / 1.000.000 × tarifa de output` |
+
+O dashboard soma esses componentes uma única vez. Quando uma tarifa publicada não existe, ela permanece indisponível em vez de ser inventada.
+
+## 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.
+
+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.

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.