@zaip-ai/cli 1.3.0 → 1.3.1

package/templates/.agents/runtime/checksums.sha256

@@ -1,11 +1,11 @@
 b146bd0c7c60b1ab43c4f71e0b1d2262c6df6da6f7053a0425f834ccb77a6b48  LICENSE
 bc02cba77e8d51e5c580f43668863dc868eda66f1ff663bfaa49fcf3ca16320e  THIRD_PARTY_NOTICES.md
 64d23f858ef51b0f996e4966d4e27c0371b437e2d2787890b1f7ad22d4ec5663  VERSION
-3cb891a0e356e49966a39b890124354209a6f535620c0b7577eb006aad31f924  bin/zaip.mjs
+1e9e3713401dbc4f58f4411a3ff426fe1527c911afe6156a38f9dec18a89f85a  bin/zaip.mjs
 bed6ab1fda844209edc628c2a675021ad6acb9a2f7ecb7ae017b5a916712da24  manifest.json
 7f89219d7c567c82a51679ad136d84364bded7ac659492537e125d33b1d58a7a  migrations/001-layout-v1.json
 5f8c48b286d0b44d8fbb57a9a5d009a8a500439aa3148d750b8f193f72995c9f  migrations/002-layout-v2.json
 182a587dca8080f732cb387dbdeff4c12034a4a116efe35b4cd3c1c0a21ad10b  pnpm-lock.sha256
-ae1f182c93254b1bda1b2a12e1090aad3fac1689c5883f77b5d8ba4b1e01e3e6  provenance.json
+d2563419aaec124d758f6ff97619ec362eb2b8fd6ea43e0bc50eafe0fbebf97e  provenance.json
 b64130fccf5d6a3a0b33a15efb1ebf1ba8969342da26f4e77d410ed66af60b82  sbom.cdx.json
 b3ffedf9e146be802a15b4009f33e031dec3071ca1525e12c67606fd964a3067  schemas/contracts.schema.json

package/templates/.agents/runtime/provenance.json

@@ -6,6 +6,6 @@
   "source_origin": "zaip-aios:local-build",
   "lockfile_sha256": "382ebb27a2a951eb61280171c27116233762370d9093ab516caef216475ba4fc",
   "sbom_sha256": "b64130fccf5d6a3a0b33a15efb1ebf1ba8969342da26f4e77d410ed66af60b82",
-  "runtime_sha256": "097962b10b6ab9bd0c5370602a941510628bef3427e0828f1852a1c0762a5d9a",
-  "statement_sha256": "9ff655cc70b2ca1c19a3f6eea93294bb7f0004bc92503c00830d057e118c0dd0"
+  "runtime_sha256": "bbcdb68da07ece9966046e2d6ce1b54c5218d1318074c65e2de966b8280c02a4",
+  "statement_sha256": "391a666ed4dbc4ce18b481773a40a338bb3298e0bd503e75a0bfc4dea30f6e9c"
 }

package/templates/.agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.test.mjs

@@ -1,9 +1,18 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 const root = await mkdtemp(resolve(tmpdir(), "zaip-obsidian-test-"));
 const records = resolve(root, ".agents/records/lifecycle");
 await mkdir(records, { recursive: true });
@@ -111,22 +120,17 @@ for (const [kind, folder] of [
   assert.match(css, new RegExp(`data-path="${folder}"`));
   assert.match(index, new RegExp(`zaip-kind-${kind}`));
 }
-assert.equal(
-  await readFile(
-    resolve(
-      process.cwd(),
-      ".agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.mjs",
-    ),
-    "utf8",
-  ),
-  await readFile(
-    resolve(
-      process.cwd(),
-      "public-cli/packages/cli/templates/.agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.mjs",
-    ),
-    "utf8",
-  ),
+const sourceScript = resolve(
+  process.cwd(),
+  ".agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.mjs",
 );
+const templateScript = resolve(
+  process.cwd(),
+  "public-cli/packages/cli/templates/.agents/skills/criar-pasta-obsidian/scripts/generate-obsidian-vault.mjs",
+);
+if ((await exists(sourceScript)) && (await exists(templateScript))) {
+  assert.equal(await readFile(sourceScript, "utf8"), await readFile(templateScript, "utf8"));
+}
 assert.match(await readFile(resolve(vault, "PRDs/PRD-1.md"), "utf8"), /PRD summary/);
 
 const evidence = await readFile(resolve(vault, "Evidence/EVD-1.md"), "utf8");

package/templates/.agents/skills/zaip-skill-agent-catalog/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: zaip-skill-agent-catalog
+description: Create or change ZAIP agent catalog entries, capabilities, scopes, eligibility, and skill bindings while preserving adapter and distribution parity.
+---
+
+# Maintain the agent catalog
+
+Use when an agent identity or its operational contract changes.
+
+1. Inventory the intended capability, least-privilege write scope, execution
+   eligibility, tools, model policy, and escalation boundary before editing.
+2. Use only cataloged `codex_name` and `codex_task_name` values. Do not add ad-hoc
+   identities, task labels, or a mandatory dependency on a non-distributed skill.
+3. Bind each delivery specialty to its matching local ZAIP skill and keep `change`
+   evidence support where delivery is allowed.
+4. Validate YAML, catalog-to-skill references, specialist routing, and generated
+   Codex/Claude adapters. Update framework lock and public template only for framework
+   source changes.
+5. Report routing behavior and compatibility impact. Catalog maintenance does not
+   authorize a delivery, deployment, or approval of the agent's own work.
+
+For a new skill, use `$zaip-skill-author-skills` first.

package/templates/.agents/skills/zaip-skill-agent-catalog/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Agent Catalog"
+  short_description: "Maintain agent roles, skills, scopes, and adapter parity."
+  default_prompt: "Use $zaip-skill-agent-catalog to create or update this ZAIP agent catalog entry and validate its skill, scope, routing, and adapter bindings."

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

@@ -15,7 +15,8 @@ description: Create and audit portable ZAIP skills, triggers, resources, and rel
 6. No frontmatter aceite somente `name` e `description`. A descrição deve dizer o que faz e quando dispara.
 7. Mantenha o corpo operacional e curto. Coloque schemas/exemplos extensos em `references/`, scripts determinísticos em `scripts/` e assets somente quando reutilizáveis.
 8. Gere metadata com nome legível, descrição curta específica e prompt que mencione `$nome-da-skill`; evite prompts genéricos.
-9. Valide links relativos, encoding UTF-8, placeholders, tamanho, políticas de invocação, triggers sobrepostos e comandos citados.
-10. No framework source, rode `pnpm sync:framework-lock`, validação, testes relevantes, sync do template público, build e parity; no consumer, rode somente validação da skill, `zaip doctor` e adapters aplicáveis.
+9. Rode `scripts/audit-skill-catalog.mjs` para validar referências do catálogo, bindings obrigatórios, comandos conhecidos e contratos técnicos que não podem ser duplicados em documentação; rode `scripts/run-skill-tests.mjs` para executar todos os testes de skills descobertos.
+10. Valide links relativos, encoding UTF-8, placeholders, tamanho, políticas de invocação, triggers sobrepostos e comandos citados.
+11. No framework source, rode `pnpm sync:framework-lock`, validação, testes relevantes, sync do template público, build e parity; no consumer, rode somente validação da skill, `zaip doctor` e adapters aplicáveis.
 
 Não copie paths pessoais, portas, credenciais, integrações específicas do projeto ou runners inexistentes para uma skill core.

package/templates/.agents/skills/zaip-skill-author-skills/scripts/audit-skill-catalog.mjs

@@ -0,0 +1,49 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseDocument } from "yaml";
+
+const root = resolve(import.meta.dirname, "..", "..", "..", "..");
+const skillsRoot = resolve(root, ".agents/skills");
+const skillDirectories = (await readdir(skillsRoot, { withFileTypes: true }))
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name);
+const knownSkills = new Set(skillDirectories);
+const errors = [];
+const catalog = parseYaml(
+  await readFile(resolve(root, ".agents/config/agents/catalog.yaml"), "utf8"),
+);
+
+for (const agent of catalog.agents ?? []) {
+  for (const skill of agent.skills ?? []) {
+    if (!knownSkills.has(skill)) errors.push(`${agent.id}: references unavailable skill ${skill}`);
+  }
+}
+for (const [agentId, requiredSkill] of [
+  ["agent-frontend", "zaip-skill-frontend"],
+  ["agent-backend", "zaip-skill-backend"],
+  ["agent-designer", "zaip-skill-design-system"],
+]) {
+  const agent = (catalog.agents ?? []).find((entry) => entry.id === agentId);
+  if (!agent?.skills?.includes(requiredSkill))
+    errors.push(`${agentId}: must load ${requiredSkill}`);
+}
+const rulesSource = await readFile(resolve(skillsRoot, "zaip-skill-rules/SKILL.md"), "utf8");
+if (/\bcontext validate\b/i.test(rulesSource))
+  errors.push("zaip-skill-rules: cites unavailable context validate command");
+const sqliteSource = await readFile(
+  resolve(skillsRoot, "zaip-skill-sqlite-read-model/SKILL.md"),
+  "utf8",
+);
+if (/schema version \d+|schema \d+|requiredIndexCount|exactly these tables/i.test(sqliteSource))
+  errors.push("zaip-skill-sqlite-read-model: duplicates volatile runtime schema contract");
+
+if (errors.length > 0) throw new Error(`Skill catalog audit failed:\n${errors.join("\n")}`);
+process.stdout.write(
+  `Audited ${skillDirectories.length} skills and ${(catalog.agents ?? []).length} agents.\n`,
+);
+
+function parseYaml(source) {
+  const document = parseDocument(source, { strict: true, uniqueKeys: true });
+  if (document.errors.length > 0) throw new Error(document.errors.map(String).join("\n"));
+  return document.toJS();
+}

package/templates/.agents/skills/zaip-skill-author-skills/scripts/author-skill-scripts.test.mjs

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import test from "node:test";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const root = resolve(import.meta.dirname, "..", "..", "..", "..");
+const scripts = resolve(root, ".agents/skills/zaip-skill-author-skills/scripts");
+
+test("skill test discovery lists every checked-in skill test without executing recursively", async () => {
+  const { stdout } = await run(
+    process.execPath,
+    [resolve(scripts, "run-skill-tests.mjs"), "--list"],
+    { cwd: root },
+  );
+  assert.match(stdout, /author-skill-scripts\.test\.mjs/);
+  assert.match(stdout, /github-deploy-contract\.test\.mjs/);
+  assert.match(stdout, /refactor-scripts\.test\.mjs/);
+});
+
+test("skill catalog audit validates the checked-in catalog and technical contracts", async () => {
+  const { stdout } = await run(process.execPath, [resolve(scripts, "audit-skill-catalog.mjs")], {
+    cwd: root,
+  });
+  assert.match(stdout, /Audited \d+ skills and \d+ agents/);
+});

package/templates/.agents/skills/zaip-skill-author-skills/scripts/run-skill-tests.mjs

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const skillsRoot = resolve(import.meta.dirname, "..", "..");
+const tests = (await files(skillsRoot))
+  .filter((path) => /(?:^|[\\/])[^\\/]+\.(?:test|tests)\.(?:mjs|cjs|js)$/i.test(path))
+  .sort();
+
+if (tests.length === 0) {
+  process.stdout.write("No ZAIP skill tests found.\n");
+  process.exit(0);
+}
+
+if (process.argv.includes("--list")) {
+  process.stdout.write(`${tests.join("\n")}\n`);
+  process.exit(0);
+}
+
+await new Promise((resolveRun, reject) => {
+  const child = spawn(process.execPath, ["--test", ...tests], { stdio: "inherit" });
+  child.once("error", reject);
+  child.once("exit", (code) =>
+    code === 0 ? resolveRun() : reject(new Error(`Skill tests failed (${code})`)),
+  );
+});
+
+async function files(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const path = resolve(directory, entry.name);
+      return entry.isDirectory() ? files(path) : entry.isFile() ? [path] : [];
+    }),
+  );
+  return nested.flat();
+}

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

@@ -8,3 +8,4 @@ description: Implement backend APIs, persistence, and integration boundaries ins
 1. Confirmar contrato de entrada e saída, limites de persistência e dependências antes da alteração.
 2. Preservar a direção de dependências e manter detalhes de infraestrutura atrás da fronteira do módulo.
 3. Aplicar arquitetura e CQRS proporcionalmente ao contrato alterado: não introduzir camadas, migrações ou gates pesados quando a mudança local não os exige. Cobrir o comportamento alterado com testes focados e registrar incompatibilidades, migrações ou riscos de integração.
+4. Aplicar [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md): metadados para estrutura/migração, fluxo autorizado e registros específicos para persistência, logs correlacionados para correções e observação direta de API/fila/cache/integração. SQL não é obrigatório quando inaplicável. Correlacionar UI e backend quando o AC exigir o fluxo completo; registrar ambiente, versão, limitações e fallback finito sem expor dados sensíveis.

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

@@ -9,7 +9,7 @@ description: Maintain Change narrative, decisions, evidence, rollback, and resul
 2. Antes da primeira mutação, confirme que a Change existe e que sua origem é Task, SPEC ou PRD real.
 3. Mantenha `change.md` como narrativa viva: plano, implementação, decisões, evidências, evals, testes e resultado.
 4. Atualize em marcos relevantes, não a cada comando; derive a lista final de arquivos do Git diff.
-5. Relacione cada evidência à Task e aos Acceptance Criteria que ela comprova.
+5. Relacione cada evidência à Task e aos Acceptance Criteria que ela comprova. Para planejar, registrar ou avaliar prova de entrega, leia [o contrato de prova observável](references/observable-evidence.md); concentre ali cenários, estados, fallbacks e validade, sem duplicar relatórios.
 6. Registre decisões curtas na seção principal; use `decisions/` ao lado da Change somente para decisões consequenciais que mereçam histórico próprio.
 7. Para risco `critical`, mantenha anexos de threat model, rollout e rollback; para riscos menores, prefira seções inline.
 8. Antes de concluir, elimine placeholders, registre desvios/rework, comprove todos os ACs e resuma o resultado observado.

package/templates/.agents/skills/zaip-skill-change/references/observable-evidence.md

@@ -0,0 +1,83 @@
+# Prova observável por critério de aceite
+
+Contrato operacional de `REQ-WORK-002`, compartilhado por execução, frontend, backend e revisão. Use para entregas novas ou verificações explicitamente retomadas; não reabra nem reclassifique entregas históricas.
+
+## Preparar a prova
+
+Antes de implementar, identifique para cada AC o cenário discriminante, a expectativa, a modalidade necessária e o ambiente autorizado. Comece pelo cenário de maior risco quando isso permitir detectar uma direção errada cedo. Não exija uma bateria completa por captura nem use duração isolada como prova de falha.
+
+Registre uma observação com vínculos Task/Change/Execution/Run/AC, procedimento ou cenário, expectativa, resultado observado, momento real da observação, ambiente, candidato efetivamente executado, locators e limitações. Dados indisponíveis permanecem explícitos; horário de registro não deve ser apresentado como horário de execução.
+
+Uma observação é produzida uma vez e referenciada pela Validation/Evidence existente. Não duplique logs, screenshots ou relatórios. Uma mesma execução pode apoiar vários ACs, desde que seu resultado seja explicado para cada um. Quantidade, screenshot existente, banco com uma linha ou ausência de erro não comprovam o resultado solicitado isoladamente.
+
+## Escolher o procedimento pelo impacto
+
+| Impacto do AC | Observação necessária |
+| --- | --- |
+| Visual | Captura real da aplicação atualizada, preferencialmente pelo navegador integrado disponível. Reproduza rota, aba, filtros, período e estado pedidos; registre URL, horário, viewport e versão carregada. Examine a imagem contra a expectativa e registre quem examinou e o resultado. Imagem gerada, render de teste, API e código não substituem essa prova. |
+| Interação frontend | Execute a interação e confira o efeito. Persistência, dados, acessibilidade e desempenho exigem comprovação própria quando fazem parte do AC; screenshot é complementar. |
+| Estrutura/migração | Compare metadados reais com o contrato: colunas, tipos, índices e restrições pertinentes. |
+| Persistência | Execute o fluxo autorizado e consulte somente os registros necessários, incluindo valores, relacionamentos e ausências esperadas. |
+| Correção de erro | Reproduza o cenário, examine logs disponíveis e correlacione o resultado com os logs posteriores. Ausência de prova anterior é limitação explícita, não um resultado inventado. |
+| API/fila/cache/integração | Observe diretamente entrada, saída e efeito no componente. Não exija SQL quando ele não se aplica. |
+| Fluxo entre frontend e backend | Relacione a ação da interface ao efeito correspondente por identificador de cenário, requisição, operação ou registro. Testes isolados continuam sendo provas de camada, não E2E automático. |
+
+Não imponha produção se o AC admitir ambiente representativo. Se exigir produção, prova de outro ambiente permanece limitada. Para ambiente representativo ou dependências reais isoladas, declare as diferenças que podem afetar o resultado. Mocks e análise estática só confirmam as alegações que realmente exercitam.
+
+## Estados e aprovação
+
+| Estado da observação | Consequência |
+| --- | --- |
+| `confirmed` | Prova suficiente para a alegação e ambiente declarados; pode complementar a aprovação, mas não substitui os gates existentes. |
+| `limited` | Prova parcial; explicitar o que confirmou e o que falta. Não aprova a parcela sem comprovação. |
+| `pending` | Verificação ainda não realizada ou indisponível. Informar motivo, ACs, tentativas, dependência e próximo procedimento. |
+| `failed` | Resultado observado diverge da expectativa. Exige correção governada e nova prova; não trocar de ambiente só para obter verde. |
+| `not_applicable` | Modalidade sem relação com o AC/escopo, com justificativa objetiva; não equivale a aprovar o AC. |
+
+Falha de ferramenta é pendência, não reprovação do produto. Não registre `passed` para ausência de captura, timeout de ferramenta, mocks insuficientes ou N/A. Se faltar prova obrigatória, mantenha o aceite dependente pendente e encerre a tentativa como `blocked` quando necessário; preserve a implementação e prossiga apenas com trabalho independente. Não deixe uma Task em execução indefinida para ocultar o bloqueio.
+
+## Fallback finito
+
+Para a mesma capacidade e condição bloqueadora, registre no máximo três tentativas: uma inicial, no máximo uma repetição após ação concreta de recuperação e no máximo uma alternativa já disponível e permitida. A repetição sem mudança observável não é autorizada. Uma alternativa não exige repetir antes um mecanismo sabidamente indisponível.
+
+| Indisponibilidade | Alternativa e resultado |
+| --- | --- |
+| Navegador integrado | Após recuperação concreta e única repetição, tente uma captura real por outro mecanismo disponível e permitido; registre qual. Não instale ferramentas, altere permissões ou contorne controles. |
+| Nenhuma captura possível | Registre “validação visual pendente por indisponibilidade da ferramenta”; preserve prova técnica sem chamá-la visual. |
+| Banco/serviço/log | Uma alternativa representativa ou integração com dependências reais isoladas, dentro da autoridade existente. Se a equivalência não satisfizer o AC original, registre prova limitada e pendência restante. |
+| Somente mocks/estática | Registre alcance limitado para alegações de funcionamento real; não transforme falta de acesso em N/A. |
+| Limite atingido | Registre dependência, procedimento de retomada e ACs afetados; não entre em loop nem repita pedidos de confirmação. |
+
+ACs que compartilham a mesma falha de ferramenta compartilham o diagnóstico e não multiplicam tentativas. Trocar de Run não zera esse histórico. Verificação longa ainda em progresso não é uma nova tentativa nem deve ser interrompida só pelo relógio; use os limites operacionais existentes.
+
+## Proteção e retomada
+
+Use somente ambientes autorizados, dados mínimos e locators sanitizados. Remova credenciais, tokens, parâmetros sensíveis de URLs, dados pessoais desnecessários e segredos dos materiais antes do registro. Não execute escritas em produção para obter prova sem autoridade específica. Hash identifica conteúdo, não demonstra autenticidade da observação.
+
+Reavalie validade quando mudarem candidato executável, schema, configuração, permissões, flags, dependências, dados relevantes, período, viewport, cenário ou AC. Não infira ambiente equivalente apenas do commit. Preserve observações antigas como histórico e registre o delta, sem reescrever horários ou autoria.
+
+O recorte atual não autoriza reuso aprovador entre Runs, nova rota de retomada nem dispensa revisão/finalização. `task resume` e `execution run --recheck-blocked-state` conservam seus contratos; a rechecagem autônoma exige candidato novo e não reinicia orçamento. Se apenas uma ferramenta voltou com candidato igual, registre a pendência resolvida na tentativa autorizada e mantenha os vínculos exigidos; não finja que uma prova antiga foi executada de novo.
+
+## Limite de automação
+
+A política define o que o executor e o revisor devem comprovar. O registro CLI valida estrutura e vínculos; ele não executa o comando declarado, não examina pixels e não consulta banco automaticamente. Observações referenciadas por uma aprovação devem ser confirmadas e compatíveis; observação isolada não aprova. Históricos V2 sem observações permanecem legíveis e não são promovidos retroativamente a prova visual ou de produção.
+
+## Registrar sem duplicar a prova
+
+`validation observe` aceita um objeto JSON `EvidenceObservationV1` diretamente em `--observation`, com limite de 256 KiB UTF-8 (o shell pode impor limite menor). A CLI não abre arquivos de entrada; `--observation-file` não é suportado. Essa escolha evita introduzir uma nova superfície de leitura de arquivos/reparse points nesta fatia. O comando grava exclusivamente um novo `artifacts/observations/OBS-*.md` na Change vinculada, sem alterar o estado da Task ou criar Validation aprovada. IDs e vínculos devem existir; exemplos abaixo são placeholders, não resultados executados.
+
+```text
+zaip validation observe --observation '<objeto JSON sanitizado com os campos abaixo>' --json
+zaip validation record --id TEST-CENARIO --task TASK-ID --acceptance AC-ID --command "procedimento realmente executado" --outcome passed --locators caminho/relatorio --run RUN-ID --commit SHA --executed-at ISO --asserted-outcome "resultado observado para o AC" --json
+zaip evidence record --id EVD-CENARIO --task TASK-ID --summary "alcance comprovado" --outcome passed --run RUN-ID --validation TEST-CENARIO --observations OBS-CENARIO --json
+```
+
+O JSON usa `schema_version: 1`, `id`, `task_id`, `change_id`, `execution_id`, `run_id`, `acceptance_ids`, `proof_kind`, `state`, `scenario`, `expected`, `observed`, `observed_at`, `examiner_id`, `commit_sha`, `candidate_version`, `environment`, `visual`, `correlation_ids`, `locators`, `limitations`, `not_applicable_reason`, `pending_reason`, `dependency`, `resume_plan` e `attempts`. Consulte o schema e os exemplos testados em `packages/specs/src/assurance/artifacts.ts` e `assurance-contract.test.ts`; não invente campos V2. A versão candidata identifica o artefato efetivamente observado; o SHA Git continua sendo o vínculo exigido pelo assurance.
+
+`environment` descreve classe, identificador e versão. Estado `confirmed` exige versões observadas do candidato e do ambiente; sem elas, registre limitação/pendência, não um valor presumido. Integração confirmada exige `correlation_ids` do cenário; API ou persistência isoladas não exigem correlação artificial. Prova visual confirmada também exige `visual.url`, `viewport` no formato `1366x768`, `captured_at`, `loaded_version` igual a `candidate_version` e `examination`. Use URL base sem credenciais, query ou fragmento; registre filtros e estado relevantes no cenário sanitizado, nunca tokens de acesso. Preencha indisponibilidade com `null` nos campos permitidos, sem atribuir uma observação inexistente a produção.
+
+`validation record` também admite `failed` e `not_applicable` (este exige `--reason`); esses registros não alimentam Evidence aprovada. Informe `--executed-at` e `--asserted-outcome` nas novas entregas. A omissão desses campos conserva o comportamento legado e não demonstra que a CLI executou um teste naquele horário. Pendência de ferramenta usa `validation observe`, não `failed` de produto.
+
+`evidence record --observations` e a leitura de assurance conferem estado confirmado, identidade do arquivo e os vínculos de Task/Change/Execution/Run/AC/candidato. A lista de ACs da observação pode ser um subconjunto da Evidence: uma observação não comprova implicitamente os demais ACs. Observações sem referência ficam como histórico e não contam para aprovação. A seleção e suficiência de todas as modalidades obrigatórias continuam sendo responsabilidades do executor/revisor; este recorte não implementa detecção automática de obrigação visual, invalidação global por ambiente ou contador de tentativas entre Runs.
+
+A compatibilidade preserva o formato V2 e a leitura histórica, não a aplicação deste contrato por clientes antigos. Não use um downgrade da CLI para qualificar observações novas nem interprete um `passed` legado como certificação deste contrato.

package/templates/.agents/skills/zaip-skill-dashboard-diagnostics/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: zaip-skill-dashboard-diagnostics
+description: Diagnose a served ZAIP dashboard incident across launcher, SQLite snapshot, API, UI preset, and browser evidence; use for stale, slow, or inconsistent dashboard behavior.
+---
+
+# Diagnose a served dashboard
+
+Use for a reported dashboard regression, not for generic database rebuilding.
+
+1. Capture the affected route, tab, filter/preset, expected value, and time range.
+   Validate that exact path rather than a generic health response.
+2. Identify the launcher-owned process and runtime generation without terminating
+   another task's healthy session. Check health, served artifact, API payload, and
+   SQLite snapshot as distinct evidence layers.
+3. Rebuild or compare the disposable read model only when source/snapshot drift is
+   evidenced. Use `$zaip-skill-sqlite-read-model` for that operation.
+4. Compare displayed metrics with factual telemetry/read-model facts, explaining
+   rounding and unavailable values. Do not invent missing work or duration.
+5. Measure the served launcher/runtime flow for performance. A source-only query or a
+   failed browser setup is not browser proof.
+6. If code changes are requested, use the appropriate delivery skill; diagnostics do
+   not authorize a mutation or lifecycle closure.

package/templates/.agents/skills/zaip-skill-dashboard-diagnostics/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Dashboard Diagnostics"
+  short_description: "Trace served dashboard failures with layered evidence."
+  default_prompt: "Use $zaip-skill-dashboard-diagnostics to diagnose this ZAIP dashboard regression using the exact affected tab, preset, API, snapshot, and browser evidence."

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

@@ -12,7 +12,7 @@ Use esta skill somente quando o usuário pedir execução. `prepare` não autori
 3. A partir da tentativa explícita de `execute`, classifique uso como `execution`; inicie Execution, Changes, Tasks elegíveis e Runs com atribuição ao nível de entrada (`task`, `spec` ou `prd`). Ausência de diff não retroage a fase: registre `changed_files` vazio e o resultado real.
 4. Execute a ordem topológica. Paralelize apenas Tasks independentes cujos arquivos, módulos, migrations, ambientes e recursos não conflitem.
 5. Antes de integrar agentes paralelos, compare diffs, testes e efeitos; reconcilie o resultado no workspace canônico.
-6. Registre decisões humanas/IA, uso por fase, evidências por AC, testes, evals e arquivos alterados.
+6. Registre decisões humanas/IA, uso por fase, evidências por AC, testes, evals e arquivos alterados. Antes de implementar, aplique [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md): cenário, expectativa, ambiente autorizado, prova necessária e fallback finito. Falta de prova obrigatória impede aceite, não trabalho independente.
 7. Para toda Task com mutação, produza um commit canônico isolado antes de `completed`, com provider efetivo exclusivamente `CODEX` ou `CLAUDE` e sem `AUTO`. Linhagem evidenciada usa `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <título da Task>` com blocos disponíveis; Task sem PRD/SPEC usa `[CODEX|CLAUDE] [Task-first:XXXX] <título da Task>`. Limite o assunto a 96 caracteres sem cortar palavras, preserve IDs completos disponíveis nos trailers `ZAIP-PRD`, `ZAIP-SPEC`, `ZAIP-Task`, `ZAIP-Change`, `ZAIP-Execution` e `ZAIP-Agent`, e não combine Tasks no mesmo commit. Commit funcional sem Task só é permitido na exceção explícita de deploy particionado e usa `[CODEX] <título funcional>` sem `ZAIP-Task`.
 8. Respeite a política do plano: use `zaip verify --changed --risk <risk>` no modo `scoped`; reserve `pnpm verify` para `full`, risco critical ou gate final exigido.
 9. Em cada `run usage`, leia `budget.context_refresh_required` e `budget.checkpoint_required`. O runtime grava o checkpoint sanitizado em `.local/checkpoints/`; quando sinalizado, reconstrua contexto somente de IDs ativos, diff e findings, descarte outputs brutos antigos e continue apenas com autoridade.

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

@@ -1,10 +1,11 @@
 ---
 name: zaip-skill-frontend
-description: Implement accessible frontend experiences and component integration inside apps/frontend. Use for declared frontend delivery that consumes the central design contract without changing it.
+description: Implement accessible frontend experiences in apps/frontend and dashboard React surfaces, without changing runtime or SQLite.
 ---
 
 # Entregar frontend
 
-1. Confirmar que o escopo está em `apps/frontend/**`; encaminhar tokens, componentes centrais e `DESIGN.md` para o agente de design.
+1. Confirmar `apps/frontend/**` ou dashboard React (`.agents/dashboard/apps/frontend/**`, `.agents/dashboard/modules/**/src/react/**`); nunca autoriza runtime, SQLite ou server.
 2. Ler o contrato visual aplicável antes de alterar componentes e preservar acessibilidade, semântica e estados de carregamento/erro.
-3. Validar a interação afetada com teste focado, typecheck ou build proporcional e relatar as evidências do critério de aceite.
+3. Aplicar [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md): definir cenário/expectativa por AC, executar a interação afetada e conferir seu efeito; teste, typecheck e build são proporcionais e não substituem comportamento observado.
+4. Se houver impacto visual, obter e examinar screenshot real da versão carregada no estado pedido. No dashboard, preservar render determinístico e verificação do bundle servido. Indisponibilidade segue o fallback finito: mantém o AC visual pendente, não invalida prova técnica independente nem autoriza aprovação integral.

package/templates/.agents/skills/zaip-skill-frontend/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP Frontend Delivery"
-  short_description: "Implement accessible frontend inside declared product scope."
-  default_prompt: "Use $zaip-skill-frontend to implement an accessible frontend change inside its declared scope."
+  short_description: "Implement accessible apps/frontend and dashboard React surfaces."
+  default_prompt: "Use $zaip-skill-frontend for apps/frontend or dashboard React; never runtime, SQLite, or server."

package/templates/.agents/skills/zaip-skill-github-deploy/SKILL.md

@@ -12,11 +12,11 @@ Treat deploy as Git-only publication. An explicit current-turn request to `deplo
 ## Authorization
 
 - Require an explicit deploy, push, publicar, publicação, GitHub publication, or failed-deploy repair request in the current turn.
-- The request authorizes the initial publication, reconciliation needed to publish the selected branch, commits covering all versionable pending changes in the selected worktree, and up to five repair cycles needed to make required local and remote GitHub checks pass.
+- The request authorizes the initial publication, automatic reconciliation needed to publish the selected branch, commits covering all versionable pending changes in the selected worktree, and up to five repair cycles needed to make required local and remote GitHub checks pass. Do not stop merely because the worktree is dirty, history is behind/diverged, generated files are pending, or a local gate has a repairable failure.
 - Limit repairs to the intended repository state and the evidenced failure. Do not add unrelated features or broaden product scope.
 - Never force push, rewrite history, replace remotes, change credentials or Git/SSH configuration, bypass checks, or deploy to another service.
-- Do not create lifecycle artifacts for an explicit Git-only publication request. The deploy authorization permits staging the complete selected worktree with `git add -A` after secret, size, and ignore checks; it never authorizes changes outside that worktree.
-- Map a functional group to PRD/SPEC/Task only when evidence exists; otherwise use `[CODEX] <functional title>` without `ZAIP-Task`. Omit nonexistent lineage blocks and trailers. Broad staging is authorized only by the exact current-turn deploy request; force, destructive reset, history rewrite, and credential changes remain prohibited.
+- Do not create lifecycle artifacts for an explicit Git-only publication request. The deploy authorization permits staging every inventoried versionable path in the selected worktree after secret, size, and ignore checks; it never authorizes changes outside that worktree.
+- Map a functional group to PRD/SPEC/Task only when evidence exists; otherwise use `[CODEX] <functional title>` without `ZAIP-Task`. Omit nonexistent lineage blocks and trailers. Complete inventoried-path staging is authorized only by the exact current-turn deploy request; force, destructive reset, history rewrite, and credential changes remain prohibited.
 
 ## Mandatory authorization record
 
@@ -37,19 +37,19 @@ The conversation and terminal deploy report are the authority record for Git-onl
 2. Select exactly one publishing worktree. A clean worktree on another branch or a detached verification worktree does not join the deploy. The selected worktree is the complete publication scope.
 3. Report concurrent activity, but do not block solely because the selected worktree is dirty or contains mixed changes; the explicit “faça deploy” authorization includes those changes. Stop only for an unresolved index conflict, secret/oversize file, authentication failure, or destructive/rewrite requirement.
 4. Prunable or missing worktrees are reported but never pruned automatically. Dirty detached or temporary worktrees are never deleted, reset, stashed or copied into the publishing worktree implicitly.
-5. Fetch once and compute ahead/behind for the publishing branch. If it is behind or diverged, reconcile only the selected branch under this deploy authorization.
+5. Fetch once and compute ahead/behind for the publishing branch. If it is behind or diverged, automatically reconcile only the selected branch under this deploy authorization and continue; divergence is not a blocker by itself.
 6. Before reconciliation, create a recoverable branch reference and preserve tracked plus untracked changes in a named stash. Verify both references before proceeding. Use `rebase` unless the user explicitly selected `merge`.
-7. Apply the bounded reconciliation without force. Restore with `git stash apply`, retain the stash until publication succeeds, and resolve generated aggregate conflicts by regenerating them from canonical sources.
-8. After restoration, prove that no unmerged paths remain, re-inventory the diff, and only then begin functional partitioning.
+7. Apply the bounded reconciliation without force. Restore with `git stash apply`, retain the stash until publication succeeds, and resolve generated aggregate conflicts by regenerating them from canonical sources. For ordinary textual conflicts, combine both sides when safe; use the selected worktree's intended version only when the diff and commit history establish that it supersedes the remote version.
+8. After restoration, prove that no unmerged paths remain, re-inventory the diff, and only then begin functional partitioning. Continue automatically through recoverable conflicts and pending repairs; stop only for a genuine terminal blocker defined below.
 
 ## Repair-loop integrity
 
 - A publication cycle is: run deploy preflight, inventory the intended pending diff, synchronize, create any required functional commits with explicit pathspecs, push, and verify the remote hash. When no intended pending diff exists, publish already-formed commits. Run only gates required or evidenced by repository Rules, the active Change, or failed remote CI.
-- Inventory the complete pending diff, run the safety gates, then stage the selected worktree with `git add -A` and commit it. Do not require functional partitioning for this explicit broad-deploy mode.
+- Inventory the complete pending diff, run the safety gates, then stage the reviewed inventory with `git add -- <explicit-pathspecs>` and commit it. Generate pathspecs from the reviewed tracked and untracked inventory; do not use `git add -A`, broad globs, or paths outside the selected worktree. Do not require functional partitioning for this explicit broad-deploy mode.
 - Run each diagnostic, gate, fetch, stage, commit, push, and hash verification at most once per cycle.
 - Start a new cycle only after a repository change or new remote evidence. Never repeat an unchanged failing command hoping for a different result.
 - Continue until all required checks pass or a terminal blocker occurs. Stop after five repair cycles, or when the same root cause remains after two repairs.
-- Treat authentication, unavailable credentials, unauthorized branch divergence, secret exposure, destructive changes, GitHub outages, and ambiguous scope expansion as terminal blockers.
+- Treat authentication, unavailable credentials, unresolved conflicts after bounded repair, secret exposure, destructive changes, GitHub outages, and ambiguous scope expansion as terminal blockers. Ordinary branch divergence, dirty state, untracked versionable files, generated projections, lint/format failures, and other repairable pending work are not blockers: repair them within the selected worktree and continue under the same authorization.
 
 ## Prove folder-scoped SSH first
 
@@ -71,11 +71,11 @@ Run preflight once at the start of the authorized deployment. On failure, stop.
    - Turbo cache hits are valid only when the active work did not originate from a failed remote CI gate.
    - When repairing failed CI, reproduce the exact failed gate once per repair cycle with Turbo cache bypassed when applicable.
 4. If a local gate fails, capture the exact failing command and error, make the smallest authorized repair, update lifecycle evidence, and start the next cycle without asking for another deploy authorization.
-5. After all required local gates pass, stage the complete selected worktree with `git add -A`. If a file is secret, oversized, ignored by policy, or outside the selected worktree, exclude it and report the reason; otherwise include it.
+5. After all required local gates pass, stage each reviewed selected-worktree path with `git add -- <explicit-pathspecs>`. If a file is secret, oversized, ignored by policy, or outside the selected worktree, exclude it and report the reason; otherwise include it.
 
 ## Synchronize and publish each cycle
 
-Fetch the selected remote and current branch once per publication cycle, without SSH overrides. Compute ahead/behind against the fetched ref. When local is behind or diverged, apply the recorded bounded reconciliation strategy; stop if it cannot be completed safely. Never reset or force.
+Fetch the selected remote and current branch once per publication cycle, without SSH overrides. Compute ahead/behind against the fetched ref. When local is behind or diverged, apply the recorded bounded reconciliation strategy and continue after successful verification; stop only if it cannot be completed safely within the bounded repair cycles. Never reset or force.
 
 Commits created during Task execution use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`: the effective executing-agent prefix followed by compact lineage.
 

package/templates/.agents/skills/zaip-skill-lifecycle-closure/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: zaip-skill-lifecycle-closure
+description: Diagnose and safely reconcile ZAIP delivery closure when a Task, Change, Execution, or Run is stuck, missing evidence, or receives a late finalizer.
+---
+
+# Close ZAIP lifecycle safely
+
+Use for a named Task, Change, Execution, or Run that failed to converge. Start from
+the supplied ID and canonical record; never scan ordinary history to guess a target.
+
+1. Separate read-only diagnosis from repair. Inspect terminal states, typed Evidence,
+   finalization barrier, observed sub-runs, and lifecycle mutation-lock ownership.
+2. Preserve fast-path execution evidence. A technical test, a finished Run, or a late
+   finalizer alone does not close delivery: missing eligible executor, finalizer, or
+   typed Evidence remains `blocked`.
+3. For a late finalizer, reconcile its exact root and `agent_path`; do not replace it
+   with a shared-session scan. Release lifecycle mutation locking before any
+   usage-attribution reconciliation to avoid capture deadlocks.
+4. Before a mutating recovery, confirm the installed CLI supports the command and
+   require explicit authorization. Reconciliation must be idempotent, scoped to the
+   named active root, and must not create agents or fabricate telemetry.
+5. Persist observed evidence before terminal Task, Change, and Execution state; refresh
+   manifests before the root Run outcome. Report technical success and formal closure
+   separately.
+
+Use `$zaip-skill-reconcile-telemetry` only for missing observed usage after lifecycle
+identity is correct; it is not a substitute for closure.

package/templates/.agents/skills/zaip-skill-lifecycle-closure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Lifecycle Closure"
+  short_description: "Diagnose and reconcile stuck delivery lifecycle closure."
+  default_prompt: "Use $zaip-skill-lifecycle-closure to diagnose a named ZAIP Task, Change, Execution, or Run that is stuck or missing finalization evidence."

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

@@ -58,3 +58,7 @@ Durante essa etapa, a Execution universal `interaction` e sua Run raiz continuam
 1. Antes de entregar um PRD, construa a matriz parental completa de ACs e outcomes e produza pelo menos três validações e três Evidences próprias.
 2. As modalidades mínimas são cross-SPEC E2E, spec review e quality review por autor/Run independente, todas no commit final esperado.
 3. Cada outcome possui Evidence explícita. SPECs e Tasks aprovadas são pré-condições, não substitutos para a prova de integração e de resultado no nível do PRD.
+
+# Referência visual condicional
+
+Quando a PRD citar UI ou referência visual, registre rota/aba, família de componente, colunas/linhas/paginação, estados e responsividade como invariantes observáveis, sem prometer prova visual inexistente.