@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/skills/zaip-skill-setup/references/basic-onboarding.md

@@ -0,0 +1,41 @@
+# Onboarding básico
+
+Instalar ou atualizar prepara o projeto para uso; não é uma entrevista para redesenhar
+o framework. Não ofereça criação de agentes, alterações do core, modelos/effort,
+autonomia ou lógica de orquestração. Preserve a seleção manual do host, os booleanos
+de clients/tracking, configurações extras e customizações já existentes.
+
+## Verificação proporcional
+
+| Evidência | O que comprova | Pendência real |
+| --- | --- | --- |
+| Versões locais e resultado do init | Pré-requisitos do perfil e arquivos instalados | Dependência ausente/incompatível |
+| doctor e adapters check | Integridade e configuração da instalação | Finding exato, sem suíte do produto |
+| hook status e eventos observados | Integração com o host | Aprovação/capacidade ainda não confirmada |
+| Git disponível e working tree reconhecida | Repositório local utilizável | Git/repositório ausente |
+| user.name e user.email | Identidade local configurada | Identidade pendente |
+| origin reconhecido como GitHub | Destino local declarado | Remote ausente ou de outro serviço |
+| rev-parse --verify HEAD^{commit} | Existe um primeiro commit válido na história local | HEAD sem commit válido |
+
+Um SHA local não prova push, autenticação, permissões ou existência remota. A inspeção
+não faz chamadas ao GitHub. Quando o pedido incluir configurar GitHub, use a skill
+correspondente e evidência real da operação autorizada; nunca invente acesso.
+Instalação pode concluir sem Git/commit/GitHub: diferencie “instalado” de “pronto para
+entregas”. Não crie commit, faça push ou provisionamento automaticamente no init.
+
+Não testar a UI, abas, exports ou fluxos internos do dashboard ZAIP em consumidores.
+O bootstrap SQLite e doctor da instalação são checks distintos. O builder valida os
+contratos internos que modificar. Também não testar formulário/backend do produto
+do consumidor para comprovar instalação do framework.
+
+## Encerramento
+
+Relate versão, alterações/backup, dependências e pendências observadas. Sem pendência,
+encerre sem perguntas. Uma pendência não autoriza proposta de mudança do core.
+Peça apenas informação indispensável que não exista na configuração ou no pedido;
+não repita decisões, reinstalações ou perguntas sobre clientes já selecionados.
+
+Exemplos: instalação nova sem HEAD é instalada com commit inicial pendente; atualização
+de projeto configurado preserva preferências e confirma o HEAD existente; pedido
+“primeiros passos” não propõe agentes novos nem revisão da orquestração. Personalização
+profunda é opt-in explícito e pertence ao contrato separado de configuração.

package/templates/.agents/skills/zaip-skill-setup/references/codex-activation.md

@@ -0,0 +1,40 @@
+# Ativação Codex em instalação e atualização
+
+O instalador pode registrar somente o projeto atual como confiável na configuração do host,
+quando houver capacidade/permissão, com backup, edição precisa, idempotência e leitura de
+confirmação. Preserve outros projetos, modelos, perfis, hooks e preferências. Configuração
+inválida, formato não editável com segurança ou gravação concorrente é preservada e produz
+uma pendência concreta. `--project-only` não lê nem altera configuração global; restrição
+explícita do usuário prevalece. Nunca confie recursivamente em uma pasta pai.
+
+Relate confiança, aprovação de hooks e disponibilidade dos agentes separadamente. Arquivos
+instalados não comprovam agentes carregados; ausência de metadados nativos é “não confirmado”.
+Se uma entrega encontrar agente ausente, diagnostique a identidade/capacidade realmente
+listada e a compatibilidade suportada antes de sugerir recarga. Não repetir reinstalação,
+recarga ou criação de outro chat sem finding novo; não declarar ativação/reload por edição.
+
+Sempre consulte `node .agents/runtime/bin/zaip.mjs hook status --json` após instalar
+ou atualizar. `doctor` reporta hooks separadamente da validade dos arquivos.
+Use hooks somente do repositório; não instale fallback global. Preserve terceiros
+e configurações personalizadas na migração, com backup dos hooks ZAIP removidos.
+
+Sem prova atual, informe “Arquivos instalados; integração Codex ainda não validada”.
+Oriente: “Abra o ícone de hooks (âncora) na área de digitação do chat do Codex,
+sem depender da cor do ícone. Quando houver o aviso ‘precisam de revisão’, abra
+a revisão dos hooks ZAIP-AIOS e clique em Permitir tudo. Se houver terceiros,
+selecione somente ZAIP. Interruptor ligado não comprova revisão nem aprovação.”
+A âncora de resultado/estatística é outro controle; a revisão dos hooks fica no input.
+Informe essa pendência uma vez; não imponha pergunta final nem peça confirmação textual
+quando o que falta é uma ação da UI do host.
+Não peça nova aprovação quando a integração atual já estiver validada.
+
+Após o aviso, confira eventos reais pelo Codex: leitura segura e um subagente pequeno
+com início/término observados, autorizado no onboarding. Executar o script direto
+não prova aprovação. Sem confirmação, consultas e planejamento continuam disponíveis;
+entregas dependentes da integração aguardam validação. Nunca autoaprove a trust store.
+
+Stop só ocorre depois da resposta: confirme essa segunda etapa na interação seguinte,
+com recibo exato, sem gerar continuação automática. `closure_pending` não é sucesso.
+Mudanças de scripts/configuração invalidam evidência anterior; atualização sempre
+reverifica, mas não exige aprovação repetida sem necessidade. Ausência de prova é
+“não confirmado”, não prova de recusa. Telemetria pendente não deve apagar respostas.

package/templates/.agents/skills/zaip-skill-setup/scripts/onboarding-contract.test.mjs

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+const read = (relative) => readFileSync(new URL(relative, import.meta.url), "utf8");
+const setup = read("../SKILL.md");
+const config = read("../../zaip-skill-config/SKILL.md");
+const basic = read("../references/basic-onboarding.md");
+
+test("setup and first steps route to the same bounded basic contract", () => {
+  assert.match(setup, /references\/basic-onboarding\.md/u);
+  assert.match(config, /zaip-skill-setup\/references\/basic-onboarding\.md/u);
+  for (const source of [setup, config]) {
+    assert.match(
+      source,
+      /Não ofereça novos agentes, mudanças no core ou na lógica de orquestração/u,
+    );
+  }
+  const advanced = config.indexOf("## Personalização explícita (opt-in)");
+  assert.ok(advanced > config.indexOf("## Onboarding após instalação"));
+  assert.ok(advanced < config.indexOf("model_orchestration"));
+});
+
+test("consumer onboarding checks installation integrity, never the internal dashboard UI", () => {
+  assert.match(
+    basic,
+    /Não testar a UI, abas, exports ou fluxos internos do dashboard ZAIP em consumidores/u,
+  );
+  assert.match(setup, /doctor --json/u);
+  assert.match(setup, /adapters check --json/u);
+  assert.doesNotMatch(setup, /incluindo `doctor`, skills, encoding, architecture/u);
+});
+
+test("the shared contract keeps local proof distinct from external access and preserves choices", () => {
+  assert.match(basic, /HEAD\^\{commit\}/u);
+  assert.match(basic, /não prova push, autenticação, permissões/u);
+  assert.match(basic, /Não crie commit, faça push/u);
+  assert.match(basic, /booleanos\s+de clients\/tracking/u);
+  assert.match(basic, /seleção manual do host/u);
+  assert.match(setup, /não desabilite escolhas anteriores nem apague customizações/u);
+});

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

@@ -27,6 +27,7 @@ SPEC é opcional para trabalho técnico amplo; Task-first continua válida para
 2. Defina objetivo, escopo, fora de escopo, Requirements/AC, design, riscos, rollout/fallback, orçamento e perguntas bloqueantes.
 3. Para mudança técnica material, cubra propriedade dos dados, identidade e tenancy, concorrência, integrações, operação e recuperação de modo proporcional; registre resposta ou inaplicabilidade.
 4. Leia `stack` e `stack.overrides` e registre snapshot de implementação com versões exatas e fontes verificáveis; nunca invente versões.
+   Consulte o principal consumidor em `.agents/architecture/`: vincule a arquitetura escolhida/planejada e registre divergências com código/configuração e observações operacionais. Uma proposta distribuída não substitui essa decisão; trate mudança de topologia pelo histórico de decisões antes de decompor a implementação.
 4. Se vier de um PRD, mantenha `prd_id`; caso contrário, preserve a SPEC standalone.
 5. Decomponha em um blueprint técnico da própria SPEC e blueprints compactos de Tasks, verificáveis e com write scopes; dependências e paralelismo pertencem à DAG interna da SPEC. No pedido explícito de criação, use `spec create --plan`: o comando valida antes da escrita, usa criação exclusiva por arquivo e rollback compensatório em caso de falha, sem prometer transação atômica multiarquivo contra interrupção abrupta.
 6. A criação, o rework e o prepare da SPEC exigem uma Run delegada e ativa do Rafa (`zaip-agent-builder`), com propósito `execution`, sob o orquestrador do turno raiz atual; passe essa Run em `--run`, ou em `--spec-run` quando a SPEC for materializada por `prd create --plan`. Não aceite replay histórico nem a Run da Bia como autoria técnica. Não crie registros Task, Change ou Execution antes de `ready|execute`; vincule sempre a Run realmente observada e o `creation_run_id` à SPEC e agregue telemetria somente quando observada ou reconciliada.

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

@@ -15,9 +15,10 @@ overviews as an input.
    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. `.local/sqlite/` is the central per-workspace directory for locally managed
-   SQLite databases. Stable names may coexist for different purposes; retention
-   and update policy follow that purpose. Keep the dashboard database exactly at
+4. `.local/sqlite/` holds only rebuildable projections and disposable fixtures.
+   Document each database's canonical sources and reconstruction procedure.
+   Preserve unknown existing databases; unique data and controls belong in durable
+   canonical storage outside `.local`. Keep the dashboard database exactly at
    `.local/sqlite/zaip-aios-dashboard.sqlite`.
    If Windows reports `EPERM` or `EBUSY`, identify and coordinate with the owning
    dashboard. Do not create another runtime database to bypass its ownership.

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

@@ -16,6 +16,7 @@ Commit de produto exige o título canônico e IDs completos desta Task, inclusiv
 3. Para trabalho novo, use `--intent new-work` com título semântico de 4 a 10 palavras, short name, objetivo e `--write-scopes` quando o escopo já for conhecido. A captura cria a Task; somente planejamento explicitamente solicitado pode parar em `planned`/Pronto para Executar. Nunca copie ou trunque o prompt como título.
 4. Pedido avulso executável materializa e inicia Execution, Change, Task e Run raiz do `zaip-agent-orchestrator` antes da primeira mutação; a Task entra diretamente em `executing`. Definition é exclusiva de PRD e Planning é exclusiva de SPEC no board.
 5. Antes de editar com concorrência, prepare `task workspace TASK --run RUN` e consulte `task assurance TASK --json`; siga [o fluxo de candidato](../zaip-skill-execution/references/candidate-workflow.md), mantendo o lifecycle na raiz canônica.
+6. Um `index.lock` residual pode ser recuperado somente por `git-lock recover --task TASK --run RUN [--decision DEC-HUMAN-ID]`. Perfil full-access declarado validado e principal nativo autenticado autorizam automaticamente esse procedimento; demais perfis ou identidade indisponível exigem Decision humana confirmada. Isso não comprova permissões efetivas do host nem dispensa vazio, idade mínima de dez minutos, ausência de Git ativo/markers, caminho físico, stat estável e backup verificado. Consulte [fechamento canônico](../zaip-skill-lifecycle-closure/SKILL.md).
 
 ## Create e refine
 

package/templates/.agents/skills/zaip-skill-task/references/commit-policy.md

@@ -18,7 +18,7 @@ Um hook local pode ser ignorado com `--no-verify` e não é uma fronteira de seg
 
 PreToolUse localiza a Run pela correlação exata de sessão/turno e valida o registro canônico. Índice ausente, desatualizado ou Run terminal exige captura/reconciliação explícita; não autoriza pela última Task global.
 
-Stop lê apenas linhas completas acrescentadas ao transcript. Um recibo em `.local/hooks/stop-<hash>.json` guarda cursor e provas da sessão/turno. Use `node .agents/runtime/bin/zaip.mjs hook recover-stop --session SESSION --turn TURN` para repetir o evento exato após corrigir a causa. O prazo técnico do hook é 8 segundos dentro dos 10 segundos do host; não é um limite de tempo para a entrega. Falhas e descendentes ativos deixam pendência explícita; ausência de gates/finalizador leva ao bloqueio canônico, sem sucesso artificial. Stop nunca solicita continuação automática nem substitui a resposta. A CLI conduz o fechamento antes da resposta; a confirmação do evento terminal do host ocorre na interação seguinte.
+Stop lê apenas linhas completas acrescentadas ao transcript. Um recibo em `.agents/private/state/hooks/stop-<hash>.json` guarda cursor e provas da sessão/turno. Use `node .agents/runtime/bin/zaip.mjs hook recover-stop --session SESSION --turn TURN` para repetir o evento exato após corrigir a causa. O prazo técnico do hook é 8 segundos dentro dos 10 segundos do host; não é um limite de tempo para a entrega. Falhas e descendentes ativos deixam pendência explícita; ausência de gates/finalizador leva ao bloqueio canônico, sem sucesso artificial. Stop nunca solicita continuação automática nem substitui a resposta. A CLI conduz o fechamento antes da resposta; a confirmação do evento terminal do host ocorre na interação seguinte.
 
 A recuperação CLI explícita acompanha o mesmo recibo em uma chamada ativa do Codex,
 com até 45 segundos de trabalho e limite externo de 50 segundos; não amplia o prazo

package/templates/.agents/skills/zaip-skill-testing-strategy/SKILL.md

@@ -5,6 +5,24 @@ description: Map acceptance risks to focused unit, integration, contract, and en
 
 # Plan tests
 
+For site performance, use performance-engineering's equivalent three/five-run series,
+separate lab/public/field gates and retained sample ranges. Missing required evidence
+stays pending; TBT is not INP, and a CPU/LCP regression is not offset by fewer bytes.
+
+For sites/LPs, use the [site evidence contract](../zaip-skill-website-readiness/references/site-validation.md)
+after selecting the [actual changed impact](references/frontend-impact.md).
+Presentation-only edits require diff review, affected render and an inspected screenshot;
+an existing form/backend/Supabase connection or deployment does not require retesting
+unchanged flows. Full sandbox conversion belongs to new conversion contracts, changed
+submission/payload/flow, or an explicit request. Preserve network/lab/field distinctions.
+
+Use `scripts/validation-plan.mjs` with a locally prepared reviewed-impact JSON to
+select checks. This plans verification, never executes or approves it. Unknown impact
+requires inspecting the diff; it does not automatically select the full suite.
+For existing global test commands, follow [verification adoption](references/verification-adoption.md).
+
+For the verified builder opting into `.github/ci-validation.json`, use [remote validation](../zaip-skill-release-qualification/references/remote-validation.md): focused local checks, deterministic Actions catalog and coverage from the same executions. Never invoke the legacy full/local battery in addition to that route without a distinct unmet risk.
+
 Use when a change needs a proportionate verification plan or existing tests do not prove important behavior.
 Read `references/example-map.md` for a Hono and Kysely multi-tenant mutation.
 

package/templates/.agents/skills/zaip-skill-testing-strategy/references/frontend-impact.md

@@ -0,0 +1,81 @@
+# Validação de frontend pelo impacto
+
+O runtime `verify --risk lite|standard|critical --impact-file .local/temp/impact.json`
+reutiliza validation-plan.mjs e vincula changedFiles ao status Git exato. Risco não
+seleciona suíte global. Evidência visual/revisão ausente fica pendente; diff-only
+não é PASS. Consumidor nunca recebe teste do dashboard interno do ZAIP. Dashboard
+do próprio aplicativo é outra superfície, e não é excluído pelo nome.
+O agente prepara o JSON com diffReviewed/changedFiles/impacts após revisar o diff;
+não transfere essa tarefa ao usuário. Comandos automatizados pertinentes podem ser
+mapeados em `.agents/config/verification.json`, project-owned: schema_version:1,
+checks:{"affected-backend-contract":{script:"scripts/check-api.mjs",args:[]}}.
+Scripts devem existir, estar revisados e respeitar sandbox/efeitos do projeto.
+O runtime usa Node sem shell. Ausência de mapeamento/evidência não inventa aprovação.
+Use o fluxo normal de Evidence para screenshot examinado e revisão; não execute uma
+bateria global para satisfazer esse relatório parcial. Não retire checks existentes
+da CI silenciosamente.
+
+Use na criação, correção e publicação de sites, LPs e interfaces. O agente revisa
+o diff e classifica o efeito; não peça ao usuário um manifesto ou autorização para
+dispensar testes não relacionados. A existência de formulário, backend ou Supabase
+na página não torna toda edição uma mudança de integração.
+
+| Alteração observada | Verificação necessária |
+| --- | --- |
+| Cor, texto de apresentação, margem, fonte, ícone ou decoração | Diff + render da região afetada + screenshot real examinado |
+| Layout responsivo ou CSS compartilhado, sem comportamento alterado | Mesmo fluxo visual, nos viewports/componentes alcançados pelo diff |
+| Estado, interação, navegação, atributo de campo ou validação | Verificação focada do comportamento alterado; não exige automaticamente o formulário inteiro |
+| Envio, payload ou contrato de conversão | Cenários de conversão afetados em mock/sandbox, incluindo erros/retry quando aplicáveis |
+| API, persistência, auth, RLS, migration ou integração | Testes do contrato/fronteira alterados e efeitos alcançados; sem retestar fluxos alheios |
+| Site novo | Aceite das capacidades implementadas, incluindo conversão quando existir |
+| Impacto incerto | Inspecionar o diff/consumidores para resolver a dúvida; não disparar uma bateria completa por falta de classificação |
+
+## Caminho rápido visual
+
+1. Confirme que o diff só altera apresentação. CSS/texto no mesmo componente de um
+   formulário continua elegível se handlers, validações, contratos e comportamento
+   estiverem intactos. Nome/type/id/required de input, disabled, eventos, links,
+   condições de render, payload e chamadas de rede não são mera apresentação.
+2. Abra a versão atualizada, na rota e no estado afetados. Confira o resultado
+   pedido, recorte, legibilidade, sobreposição e controles alcançados pelo layout.
+   Em mudanças responsivas, confira os viewports relevantes. Não percorra o
+   formulário, não envie dados e não consulte o banco só para provar uma cor.
+3. Tire e examine screenshot real. Registre URL sem dados sensíveis, viewport,
+   versão/artefato, região alterada, expectativa e observação. Use o contrato
+   [de prova observável](../../zaip-skill-change/references/observable-evidence.md).
+   Um print gerado mas não examinado não encerra a validação visual.
+4. Build apenas se necessário para servir/publicar a alteração; lint/typecheck e
+   testes quando o diff ou uma falha observada justificar. Não imponha todos por
+   padrão e não repita prova válida na mesma tentativa, versão e estado.
+5. No deploy autorizado, mantenha identidade do artefato, smoke da tela/asset
+   alterados e rollback. A palavra deploy não adiciona E2E, formulário completo,
+   backend ou Supabase sem impacto demonstrado. Checks obrigatórios já configurados
+   no projeto não são removidos silenciosamente; explique conflitos específicos.
+
+Registre “não aplicável: contrato não alterado” para modalidades fora do escopo,
+sem afirmar que foram testadas/aprovadas. A classificação não reduz risco/assurance
+congelados, não contorna revisão/finalização nem autoriza publicação.
+
+## Seletor reutilizável
+
+O agente pode gerar um JSON local a partir do diff revisado e executar:
+
+    node .agents/skills/zaip-skill-testing-strategy/scripts/validation-plan.mjs impact.json
+
+Exemplo para mudar o espaçamento de um formulário já conectado ao backend:
+
+    {"operation":"edit","diffReviewed":true,"changedFiles":["src/ContactForm.tsx"],"impacts":["spacing"],"formPresent":true}
+
+Resultado: diff, render afetado e screenshot; sem teste de envio/backend/integração.
+Troque para operation publication-check no pós-deploy: acrescenta identidade e
+superfície publicada, mantendo o escopo visual. O helper planeja checks; não analisa
+o diff sozinho, não examina pixels e não concede aprovação. Mudanças contraditórias
+ou desconhecidas exigem revisão de impacto. Não use apenas a palavra “simples”,
+uma extensão de arquivo ou a presença de um print como prova de ausência de efeito.
+`verify --impact-file .local/temp/impact.json` reports `execution_passed` separately
+from manual evidence. Exit success means the scoped automated stage completed
+(or has no automatic checks); `status: needs-evidence` is not deployment approval.
+Attach inspected captures/review through the existing Evidence workflow without
+repeating successful scripts. Missing check configuration or a failed script
+returns nonzero; no global fallback suite runs.
+

package/templates/.agents/skills/zaip-skill-testing-strategy/references/verification-adoption.md

@@ -0,0 +1,31 @@
+# Adopt proportional verification
+
+Run `verify --changed --impact-file .local/temp/impact.json --json` with a reviewed
+impact covering the exact current Git paths. Never infer functional impact from
+the mere presence of a form, Supabase client or deployment request.
+
+Inspect `configuration.missing_checks`, `manual_checks` and `not_run_checks`.
+Missing configuration is different from inspected screenshots still pending or
+checks not run after a preceding failure. `needs-evidence` is not deployment
+approval and is not a request to rerun all successful automated tests.
+
+Map only the missing relevant checks in the project-owned
+`.agents/config/verification.json`. Preserve existing mappings and custom checks.
+Example (the referenced project script must actually exist and be reviewed):
+
+```json
+{
+  "schema_version": 1,
+  "checks": {
+    "affected-frontend-behavior": { "script": "scripts/check-frontend.mjs", "args": [] },
+    "conversion-sandbox": { "script": "scripts/check-conversion-sandbox.mjs", "args": [] }
+  }
+}
+```
+
+Do not generate a no-op script or map every name to the old global suite.
+Presentation-only changes require affected render and examined screenshots;
+submission/payload changes require the sandbox conversion contract. Do not send
+real leads or call writing APIs as evidence. Unknown impact requires diff review.
+The ZAIP internal dashboard belongs only to builder validation; a consumer's own
+dashboard is tested when its behavior changes.

package/templates/.agents/skills/zaip-skill-testing-strategy/scripts/validation-plan.mjs

@@ -0,0 +1,168 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const visual = new Set([
+  "copy",
+  "style",
+  "spacing",
+  "typography",
+  "icon",
+  "decorative-image",
+  "responsive-layout",
+  "shared-style",
+]);
+const interaction = new Set(["interaction", "state", "navigation", "field-contract", "validation"]);
+const conversion = new Set(["submission", "payload", "conversion-flow"]);
+const backend = new Set(["api", "persistence", "integration", "auth", "rls", "migration"]);
+const specialized = new Set(["seo", "image-delivery", "performance", "build-config", "dependency"]);
+const known = new Set([
+  ...visual,
+  ...interaction,
+  ...conversion,
+  ...backend,
+  ...specialized,
+  "unknown",
+]);
+const backendPath = /(^|\/)(backend|api|supabase|migrations|functions)\/|(^|\/)\.env(?:\.|$)/i;
+const frontendPath =
+  /\.(?:css|scss|sass|less|html?|jsx?|tsx?|vue|svelte|astro|svg|png|jpe?g|webp|avif)$/i;
+
+// Plans checks from a reviewed diff; this is not a diff analyzer or an approval gate.
+export function validationPlan(input = {}) {
+  const {
+    operation = "edit",
+    diffReviewed = false,
+    changedFiles = [],
+    impacts = [],
+    formPresent,
+    requestedFullFlow = false,
+    projectKind = "consumer",
+  } = input;
+  if (!["consumer", "builder"].includes(projectKind)) throw Error("Unknown project kind");
+  if (!["edit", "create", "audit", "publication-check"].includes(operation))
+    throw Error("Unknown validation operation");
+  if (
+    typeof diffReviewed !== "boolean" ||
+    typeof requestedFullFlow !== "boolean" ||
+    (formPresent !== undefined && typeof formPresent !== "boolean")
+  )
+    throw Error("Expected literal boolean flags");
+  if (!Array.isArray(impacts) || impacts.some((x) => !known.has(x)))
+    throw Error("Unknown impact; review the diff before choosing checks");
+  if (
+    !Array.isArray(changedFiles) ||
+    changedFiles.some(
+      (p) =>
+        typeof p !== "string" ||
+        !p ||
+        p.startsWith("/") ||
+        p.includes(":") ||
+        p.includes("\\") ||
+        p.split("/").includes(".."),
+    )
+  )
+    throw Error("Expected repository-relative file paths");
+  const base = {
+    operation,
+    checks: [],
+    full_conversion_flow: false,
+    backend_checks: false,
+    integration_checks: false,
+    heavy_audit: false,
+    real_submissions: false,
+    publish_authorized: false,
+    project_kind: projectKind,
+    dashboard_checks:
+      projectKind === "builder" && changedFiles.some((p) => p.startsWith(".agents/dashboard/")),
+    excluded: [],
+    reasons: [],
+  };
+  if (operation === "audit")
+    return { ...base, scope: "read-only", checks: ["read-only-inspection"] };
+  if (operation === "create")
+    return {
+      ...base,
+      scope: "creation",
+      checks: [
+        "initial-html",
+        "asset-integrity",
+        "responsive-visual",
+        "budgets",
+        ...(formPresent === false ? [] : ["conversion-sandbox"]),
+      ],
+      full_conversion_flow: formPresent !== false,
+      reasons: [
+        "New site acceptance covers its implemented conversion contract; no real submissions.",
+      ],
+    };
+  const review = (reason) => ({
+    ...base,
+    scope: "impact-review",
+    checks: ["review-diff-and-map-impact"],
+    reasons: [reason],
+  });
+  if (!diffReviewed || !changedFiles.length || !impacts.length || impacts.includes("unknown"))
+    return review(
+      "Establish actual changed behavior first; do not infer a full suite or a visual exemption from the request wording.",
+    );
+  const has = (set) => impacts.some((i) => set.has(i));
+  const onlyVisual = impacts.every((i) => visual.has(i));
+  if (
+    onlyVisual &&
+    changedFiles.some(
+      (p) =>
+        backendPath.test(p) || !frontendPath.test(p) || /(^|\/)(?:[^/]+\.)?config\.[^/]+$/i.test(p),
+    )
+  )
+    return review(
+      "Declared visual impact conflicts with changed paths; inspect the boundary instead of silently skipping checks.",
+    );
+  const checks = ["diff-review"];
+  if (has(visual) || has(interaction) || has(conversion) || impacts.includes("seo"))
+    checks.push("render-affected-ui", "inspect-screenshot");
+  if (impacts.includes("seo"))
+    checks.push("preserve-approved-design", "agent-resources-if-adopted");
+  if (has(interaction)) checks.push("affected-frontend-behavior");
+  const fullFlow = has(conversion) || requestedFullFlow;
+  if (fullFlow) checks.push("conversion-sandbox");
+  if (has(backend)) checks.push("affected-backend-contract");
+  const integrationChecks =
+    impacts.includes("integration") ||
+    impacts.includes("payload") ||
+    impacts.includes("persistence") ||
+    impacts.includes("rls") ||
+    impacts.includes("migration");
+  if (integrationChecks) checks.push("affected-integration-sandbox");
+  if (impacts.some((i) => ["auth", "rls"].includes(i))) checks.push("affected-security-policy");
+  for (const impact of impacts.filter((i) => specialized.has(i))) checks.push("affected-" + impact);
+  if (operation === "publication-check")
+    checks.push("published-artifact-identity", "served-affected-surface");
+  return {
+    ...base,
+    scope: onlyVisual && !requestedFullFlow ? "visual-only" : "targeted",
+    checks: [...new Set(checks)],
+    full_conversion_flow: fullFlow,
+    backend_checks: has(backend),
+    integration_checks: integrationChecks,
+    excluded: [
+      ...(!fullFlow ? ["full-conversion-flow"] : []),
+      ...(!has(backend) ? ["unaffected-backend"] : []),
+      ...(!integrationChecks ? ["unaffected-integrations"] : []),
+      ...(projectKind === "consumer" ? ["zaip-dashboard"] : []),
+      "unaffected-flows",
+    ],
+    reasons: [
+      onlyVisual
+        ? "Reviewed presentation-only diff: an existing form, Supabase client or deployment does not require a submission test."
+        : "Test only the changed contracts and reachable effects; expand when evidence identifies a regression.",
+    ],
+  };
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  if (process.argv.length !== 3) throw Error("Usage: node validation-plan.mjs impact.json");
+  process.stdout.write(
+    JSON.stringify(validationPlan(JSON.parse(await readFile(process.argv[2], "utf8"))), null, 2) +
+      "\n",
+  );
+}

package/templates/.agents/skills/zaip-skill-testing-strategy/scripts/validation-plan.test.mjs

@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validationPlan } from "./validation-plan.mjs";
+
+const edit = (overrides) => ({
+  diffReviewed: true,
+  changedFiles: ["apps/site/ContactForm.tsx"],
+  impacts: ["style"],
+  formPresent: true,
+  ...overrides,
+});
+test("style inside a form needs only a diff review, rendered UI and inspected screenshot", () => {
+  const plan = validationPlan(edit({}));
+  assert.equal(plan.scope, "visual-only");
+  assert.deepEqual(plan.checks, ["diff-review", "render-affected-ui", "inspect-screenshot"]);
+  assert.equal(plan.full_conversion_flow, false);
+  assert.equal(plan.backend_checks, false);
+  assert.equal(plan.integration_checks, false);
+  assert.equal(plan.real_submissions, false);
+  assert.equal(plan.publish_authorized, false);
+});
+for (const impact of [
+  "copy",
+  "spacing",
+  "typography",
+  "icon",
+  "decorative-image",
+  "responsive-layout",
+  "shared-style",
+]) {
+  test(impact + " does not trigger unchanged form, backend or integration checks", () => {
+    const plan = validationPlan(edit({ impacts: [impact] }));
+    assert.equal(plan.scope, "visual-only");
+    assert.equal(plan.full_conversion_flow, false);
+    assert.equal(plan.integration_checks, false);
+  });
+}
+test("a site with Supabase and more than three visual files still selects visual evidence only", () => {
+  const plan = validationPlan(
+    edit({
+      changedFiles: ["src/Form.tsx", "src/Title.tsx", "src/Button.tsx", "src/site.css"],
+      impacts: ["shared-style"],
+      backendPresent: true,
+      provider: "supabase",
+    }),
+  );
+  assert.equal(plan.scope, "visual-only");
+  assert.equal(plan.backend_checks, false);
+});
+test("deploy does not turn a visual change into a full conversion test", () => {
+  const plan = validationPlan(edit({ operation: "publication-check" }));
+  assert.equal(plan.full_conversion_flow, false);
+  assert.ok(plan.checks.includes("published-artifact-identity"));
+  assert.ok(plan.checks.includes("served-affected-surface"));
+});
+for (const impact of ["interaction", "state", "navigation", "field-contract", "validation"]) {
+  test(impact + " requires the affected frontend behavior, not an unrelated full form", () => {
+    const plan = validationPlan(edit({ impacts: ["style", impact] }));
+    assert.equal(plan.scope, "targeted");
+    assert.ok(plan.checks.includes("affected-frontend-behavior"));
+    assert.equal(plan.full_conversion_flow, false);
+  });
+}
+for (const impact of ["submission", "payload", "conversion-flow"]) {
+  test(impact + " cannot take the visual shortcut", () => {
+    const plan = validationPlan(edit({ impacts: ["style", impact] }));
+    assert.equal(plan.full_conversion_flow, true);
+    assert.ok(plan.checks.includes("conversion-sandbox"));
+  });
+}
+test("RLS changes test the affected backend/security boundary without blanket UI flows", () => {
+  const plan = validationPlan(
+    edit({ changedFiles: ["supabase/migrations/policy.sql"], impacts: ["rls"] }),
+  );
+  assert.equal(plan.backend_checks, true);
+  assert.equal(plan.integration_checks, true);
+  assert.equal(plan.full_conversion_flow, false);
+  assert.ok(plan.checks.includes("affected-security-policy"));
+});
+test("unknown impact requires inspection, not an automatic full suite", () => {
+  for (const overrides of [
+    { diffReviewed: false },
+    { impacts: ["unknown"] },
+    { impacts: [] },
+    { changedFiles: [] },
+  ]) {
+    const plan = validationPlan(edit(overrides));
+    assert.equal(plan.scope, "impact-review");
+    assert.equal(plan.full_conversion_flow, false);
+  }
+});
+test("backend and config paths cannot silently claim presentation-only exemption", () => {
+  for (const path of [
+    "supabase/client.ts",
+    "apps/backend/handler.ts",
+    "src/api/route.ts",
+    ".env.production",
+    "vite.config.ts",
+    "package.json",
+  ]) {
+    assert.equal(validationPlan(edit({ changedFiles: [path] })).scope, "impact-review");
+  }
+});
+test("explicit full-flow request is respected but never permits real submissions", () => {
+  const plan = validationPlan(edit({ requestedFullFlow: true }));
+  assert.equal(plan.full_conversion_flow, true);
+  assert.equal(plan.real_submissions, false);
+});
+test("creation retains complete implemented-site coverage and audits remain read-only", () => {
+  assert.equal(
+    validationPlan({ operation: "create", formPresent: true }).full_conversion_flow,
+    true,
+  );
+  assert.equal(
+    validationPlan({ operation: "create", formPresent: false }).full_conversion_flow,
+    false,
+  );
+  assert.deepEqual(validationPlan({ operation: "audit" }).checks, ["read-only-inspection"]);
+});
+test("invalid flags and ambiguous paths do not select an exemption", () => {
+  for (const input of [
+    { diffReviewed: "true" },
+    { formPresent: "false" },
+    { impacts: ["simple"] },
+    { changedFiles: ["../backend.ts"] },
+  ]) {
+    assert.throws(() => validationPlan(edit(input)));
+  }
+});
+test("SEO keeps agent files outside UI and does not trigger unrelated conversion/backend", () => {
+  const plan = validationPlan(edit({ impacts: ["seo"] }));
+  assert(plan.checks.includes("preserve-approved-design"));
+  assert(plan.checks.includes("agent-resources-if-adopted"));
+  assert.equal(plan.full_conversion_flow, false);
+  assert.equal(plan.backend_checks, false);
+  assert(plan.excluded.includes("zaip-dashboard"));
+});
+test("only affected internal builder dashboard receives dashboard coverage", () => {
+  const changedFiles = [".agents/dashboard/apps/frontend/Button.tsx"];
+  assert.equal(validationPlan(edit({ changedFiles })).dashboard_checks, false);
+  assert.equal(
+    validationPlan(edit({ changedFiles, projectKind: "builder" })).dashboard_checks,
+    true,
+  );
+  assert.equal(validationPlan(edit({ projectKind: "builder" })).dashboard_checks, false);
+});

package/templates/.agents/skills/zaip-skill-tool-setup/scripts/tool-state.mjs

@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
 import { parse, stringify } from "yaml";
 
 const [command = "list", id, field, value] = process.argv.slice(2);
-const path = resolve(".local/tools-state.yaml");
+const path = resolve(".agents/private/state/tools-state.yaml");
 let state = { schema_version: 1, profile: "default", tools: {} };
 try {
   state = parse(await readFile(path, "utf8"));