@zaip-ai/cli 1.3.0 → 1.3.1

package/templates/.agents/skills/zaip-skill-rules/SKILL.md

@@ -10,7 +10,7 @@ description: Create and validate project ZAIP Rules while preserving core Rules.
 3. Crie ou refine `.agents/rules/<nome>.md` com ID `RULE-*` único; `load` em `always`, `auto`, `file_match` ou `manual`; `priority` em `critical`, `high`, `medium` ou `low`; `max_context_tokens` positivo; `requires` com IDs existentes. Exija `globs` não vazios quando `load: file_match`.
 4. Escreva regras pequenas, imperativas e verificáveis; mova explicações extensas para Requirements ou documentação.
 5. Detecte contradições, ciclos de `requires`, duplicação de IDs e budgets excessivos.
-6. Rode `zaip doctor` e `zaip context validate --query "<cenário da Rule>"`; quando a orientação publicada mudar, rode `zaip adapters build` e `zaip adapters check`.
+6. Rode `zaip doctor` e use `zaip context inventory`, `zaip context build` ou `zaip context inspect` conforme o cenário da Rule; quando a orientação publicada mudar, rode `zaip adapters build` e `zaip adapters check`.
 
 ## Ownership
 

package/templates/.agents/skills/zaip-skill-spec/SKILL.md

@@ -43,3 +43,7 @@ SPEC é opcional para trabalho técnico amplo; Task-first continua válida para
 1. Antes de entregar uma SPEC, construa a matriz parental completa de ACs e produza pelo menos três validações e três Evidences próprias; resultados das Tasks não substituem esta camada.
 2. As modalidades mínimas são integração, spec review e quality review. O review é de autor e Run diferentes, e todos os artefatos usam o commit final esperado.
 3. Uma SPEC com Tasks `lite` continua usando rigor parental: a redução vale para a Task avulsa, não para a alegação integrada da SPEC.
+
+# UI visual condicional
+
+Quando a SPEC afetar UI, declare cada consumidor e gates de render exato; inclua bundle servido apenas se a distribuição/preview for afetada.

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

@@ -1,96 +1,28 @@
 ---
 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.
+description: Install, refresh, validate, or rebuild the disposable SQLite read model from canonical ZAIP records; use for schema drift or local dashboard data failures.
 ---
 
 # 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.
+Use this skill for the disposable read model. Its only canonical inputs are
+`.agents/records` and `.agents/config`; never use dashboard projections or lifecycle
+overviews as an input.
+
+1. Confirm Node.js 22 or newer. Install its LTS only when the user authorized a
+   prerequisite installation.
+2. Build the local runtime before rebuilding SQLite so the generated database and
+   validation code come from the same runtime revision.
+3. Prefer normal incremental refresh at dashboard startup. Rebuild only after a
+   persisted-contract change or a validation failure.
+4. Keep database files under `.local` (or another disposable ignored location).
+   If Windows reports `EPERM` or `EBUSY`, identify the owning dashboard and validate
+   an isolated generation instead of treating the locked database as evidence.
+5. Run the checked-in rebuild and validation scripts from the local runtime. They
+   are the authority for the current schema version, persisted objects, integrity,
+   views and indexes; do not duplicate those volatile values in this skill.
+6. Rebuild the dashboard artifact when the served runtime is part of the acceptance
+   path, then verify the served health endpoint and the exact affected API/query.
+
+The read model is read-only. A successful database check is technical evidence only;
+browser behavior and lifecycle closure need their own evidence.

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

@@ -1,37 +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` |
-| 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` |
+| 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,8 +32,9 @@ 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.
@@ -41,3 +44,10 @@ Quando houver conflito, prevalece a configuracao do projeto e a regra aplicavel.
 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/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/19-assurance-e-autonomia.md

@@ -15,6 +15,21 @@ O ZAIP-AIOS separa duas decisões que não devem ser confundidas: quanto de prov
 
 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.
@@ -65,6 +80,14 @@ O driver autônomo:
 - 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