@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-landing-page-forms/scripts/validate-plan.mjs

@@ -0,0 +1,306 @@
+import { lstat, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const formats = ["single-screen", "multistep", "contact-then-qualification"];
+const states = ["editing", "submitting", "invalid", "uncertain", "confirmed", "failed", "expired"];
+const identifier = /^[a-z][a-z0-9_-]{0,63}$/;
+const id = (value) => typeof value === "string" && identifier.test(value);
+const text = (value) =>
+  typeof value === "string" && value.trim().length > 0 && value.length <= 1200;
+
+// Checks declarations and internal consistency, never application behavior or consent legality.
+export function validateFormPlan(plan) {
+  const issues = [];
+  const issue = (path, code) => issues.push({ path, code });
+  const object = (value, path, keys) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      issue(path, "object_required");
+      return false;
+    }
+    for (const key of Object.keys(value)) if (!keys.includes(key)) issue(path, "unknown_key");
+    return true;
+  };
+  const requireText = (value, path) => {
+    if (!text(value)) issue(path, "description_required");
+  };
+  if (
+    !object(plan, "$", [
+      "schema_version",
+      "purpose",
+      "format",
+      "decision",
+      "steps",
+      "fields",
+      "states",
+      "recovery",
+      "persistence",
+      "submission",
+      "consents",
+      "accessibility",
+      "measurement",
+      "evidence",
+    ])
+  )
+    return { valid: false, issues, scope: "plan_coherence_only" };
+  if (plan.schema_version !== 1 || plan.purpose !== "landing-page-form-plan")
+    issue("$", "unsupported_contract");
+  if (!formats.includes(plan.format)) issue("format", "unsupported_format");
+  requireText(plan.decision, "decision");
+  const steps = Array.isArray(plan.steps) ? plan.steps : [];
+  if (
+    !steps.length ||
+    steps.length > 30 ||
+    steps.some((value) => !id(value)) ||
+    new Set(steps).size !== steps.length
+  )
+    issue("steps", "unique_ordered_step_ids_required");
+  if (plan.format === "single-screen" && steps.length !== 1)
+    issue("steps", "single_screen_one_step");
+  if (plan.format !== "single-screen" && steps.length < 2)
+    issue("steps", "multiple_steps_required");
+  if (object(plan.persistence, "persistence", ["mode", "save_points"])) {
+    const { mode, save_points: points } = plan.persistence;
+    if (!["final", "incremental", "contact-then-qualification"].includes(mode))
+      issue("persistence.mode", "unsupported_persistence_mode");
+    if (!Array.isArray(points) || !points.length || points.length > 30)
+      issue("persistence.save_points", "explicit_save_points_required");
+    let previous = -1;
+    const seen = new Set();
+    for (const [index, point] of (Array.isArray(points) ? points : []).entries()) {
+      const path = `persistence.save_points[${index}]`;
+      if (!object(point, path, ["step", "kind", "trigger", "receipt"])) continue;
+      const position = steps.indexOf(point.step);
+      if (position < 0 || position < previous || seen.has(`${point.step}:${point.kind}`))
+        issue(path, "save_point_step_order");
+      previous = position;
+      seen.add(`${point.step}:${point.kind}`);
+      if (!["draft", "registration", "qualification", "final"].includes(point.kind))
+        issue(path, "save_point_kind_required");
+      if (!["explicit-submit", "explicit-save"].includes(point.trigger))
+        issue(path, "navigation_is_not_save");
+      if (point.receipt !== "durable-server-receipt") issue(path, "save_receipt_required");
+    }
+    if (
+      mode === "final" &&
+      (!Array.isArray(points) ||
+        points.length !== 1 ||
+        points[0]?.step !== steps.at(-1) ||
+        points[0]?.kind !== "final")
+    )
+      issue("persistence", "final_save_at_last_step");
+    if (
+      mode === "contact-then-qualification" &&
+      (plan.format !== "contact-then-qualification" ||
+        !Array.isArray(points) ||
+        points.length !== 2 ||
+        points[0]?.step !== steps[0] ||
+        points[0]?.kind !== "registration" ||
+        points[1]?.kind !== "qualification" ||
+        steps.indexOf(points[1]?.step) <= 0)
+    )
+      issue("persistence", "registration_before_qualification");
+    if (plan.format === "contact-then-qualification" && mode !== "contact-then-qualification")
+      issue("persistence", "contact_flow_save_contract_required");
+  }
+  const fields = Array.isArray(plan.fields) ? plan.fields : [];
+  if (!fields.length || fields.length > 100) issue("fields", "bounded_fields_required");
+  const ids = new Set();
+  for (const [index, field] of fields.entries()) {
+    const path = `fields[${index}]`;
+    if (
+      !object(field, path, [
+        "id",
+        "step",
+        "purpose",
+        "required",
+        "conditional_on",
+        "when_hidden",
+        "classification",
+      ])
+    )
+      continue;
+    if (!id(field.id) || ids.has(field.id)) issue(path, "unique_field_id_required");
+    ids.add(field.id);
+    if (!steps.includes(field.step)) issue(path, "unknown_step");
+    requireText(field.purpose, path);
+    if (typeof field.required !== "boolean") issue(path, "required_boolean");
+    if (!["contact", "qualification", "nonpersonal"].includes(field.classification))
+      issue(path, "classification_required");
+    if (
+      field.conditional_on !== undefined &&
+      !["clear", "exclude-from-submit"].includes(field.when_hidden)
+    )
+      issue(path, "hidden_value_policy_required");
+  }
+  for (const [index, field] of fields.entries()) {
+    if (
+      field?.conditional_on !== undefined &&
+      (!ids.has(field.conditional_on) || field.conditional_on === field.id)
+    )
+      issue(`fields[${index}]`, "invalid_condition_reference");
+    const seen = new Set();
+    let cursor = field;
+    while (cursor?.conditional_on && !seen.has(cursor.id)) {
+      seen.add(cursor.id);
+      cursor = fields.find((entry) => entry?.id === cursor.conditional_on);
+    }
+    if (cursor?.conditional_on && seen.has(cursor.id)) issue(`fields[${index}]`, "condition_cycle");
+  }
+  if (
+    !Array.isArray(plan.states) ||
+    states.some((state) => !plan.states.includes(state)) ||
+    plan.states.some((state) => !states.includes(state))
+  )
+    issue("states", "submission_states_required");
+  if (
+    object(plan.recovery, "recovery", [
+      "back",
+      "preserve",
+      "exit",
+      "expiry",
+      "storage",
+      "retention",
+      "browser_data",
+    ])
+  ) {
+    for (const key of ["back", "preserve", "exit", "expiry", "retention"])
+      requireText(plan.recovery[key], `recovery.${key}`);
+    if (!["memory", "server-session", "browser-minimized", "none"].includes(plan.recovery.storage))
+      issue("recovery.storage", "contact_browser_storage_not_supported");
+    if (
+      plan.recovery.storage === "browser-minimized" &&
+      plan.recovery.browser_data !== "nonpersonal-only"
+    )
+      issue("recovery.browser_data", "browser_data_decision_required");
+    if (plan.recovery.storage === "none" && steps.length > 1)
+      issue("recovery.storage", "multistep_preservation_required");
+  }
+  if (
+    object(plan.submission, "submission", [
+      "client_validation",
+      "server_validation",
+      "confirmation",
+      "uncertain_reconciliation",
+      "navigation",
+      "qualification_update",
+      "existing_record",
+    ])
+  ) {
+    for (const key of [
+      "client_validation",
+      "server_validation",
+      "uncertain_reconciliation",
+      "existing_record",
+    ])
+      requireText(plan.submission[key], `submission.${key}`);
+    if (plan.submission.confirmation !== "durable-server-receipt")
+      issue("submission.confirmation", "durable_confirmation_required");
+    if (plan.submission.navigation !== "after-confirmation")
+      issue("submission.navigation", "navigation_is_not_persistence");
+    if (plan.format === "contact-then-qualification") {
+      requireText(plan.submission.qualification_update, "submission.qualification_update");
+      const contact = fields.filter((field) => field?.classification === "contact");
+      const qualification = fields.filter((field) => field?.classification === "qualification");
+      if (
+        !contact.length ||
+        contact.some((field) => field.step !== steps[0]) ||
+        !qualification.length ||
+        qualification.some((field) => field.step === steps[0])
+      )
+        issue("fields", "contact_then_qualification_order");
+    }
+  }
+  if (
+    object(plan.consents, "consents", [
+      "privacy_notice",
+      "service_basis",
+      "marketing",
+      "measurement",
+    ])
+  ) {
+    for (const key of ["privacy_notice", "service_basis"])
+      requireText(plan.consents[key], `consents.${key}`);
+    for (const key of ["marketing", "measurement"])
+      if (!["separate-opt-in", "not-used"].includes(plan.consents[key]))
+        issue(`consents.${key}`, "separate_consent_required");
+  }
+  if (
+    object(plan.accessibility, "accessibility", ["labels", "errors", "focus", "progress", "dialog"])
+  ) {
+    for (const key of ["labels", "errors", "focus", "progress"])
+      requireText(plan.accessibility[key], `accessibility.${key}`);
+    if (
+      plan.accessibility.dialog !== null &&
+      object(plan.accessibility.dialog, "accessibility.dialog", [
+        "escape",
+        "return_focus",
+        "alternative_exit",
+      ])
+    ) {
+      if (plan.accessibility.dialog.escape !== "close")
+        issue("accessibility.dialog.escape", "dialog_escape_required");
+      for (const key of ["return_focus", "alternative_exit"])
+        requireText(plan.accessibility.dialog[key], `accessibility.dialog.${key}`);
+    }
+  }
+  if (
+    object(plan.measurement, "measurement", [
+      "lead",
+      "policy_ref",
+      "policy_version",
+      "qualification",
+      "contracts",
+      "logs",
+    ])
+  ) {
+    if (
+      !["not-used", "new-registration-confirmed", "approved-request-contract"].includes(
+        plan.measurement.lead,
+      )
+    )
+      issue("measurement.lead", "lead_semantics_required");
+    if (
+      plan.measurement.lead !== "not-used" &&
+      (!id(plan.measurement.policy_ref) ||
+        !Number.isSafeInteger(plan.measurement.policy_version) ||
+        plan.measurement.policy_version < 1)
+    )
+      issue("measurement", "versioned_policy_required");
+    requireText(plan.measurement.qualification, "measurement.qualification");
+    if (
+      !Array.isArray(plan.measurement.contracts) ||
+      !plan.measurement.contracts.length ||
+      plan.measurement.contracts.some((value) => !id(value))
+    )
+      issue("measurement.contracts", "contract_references_required");
+    if (plan.measurement.logs !== "sanitized-codes-only")
+      issue("measurement.logs", "sensitive_logs_forbidden");
+  }
+  if (
+    !Array.isArray(plan.evidence) ||
+    !plan.evidence.length ||
+    plan.evidence.some((value) => !text(value))
+  )
+    issue("evidence", "verification_plan_required");
+  return { valid: issues.length === 0, issues, scope: "plan_coherence_only", live_verified: false };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  let result;
+  try {
+    if (process.argv.length !== 3) throw new Error();
+    const info = await lstat(process.argv[2]);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 64 * 1024) throw new Error();
+    result = validateFormPlan(JSON.parse(await readFile(process.argv[2], "utf8")));
+  } catch {
+    result = {
+      valid: false,
+      issues: [{ path: "$", code: "plan_input_invalid" }],
+      scope: "plan_coherence_only",
+      live_verified: false,
+    };
+  }
+  console.log(JSON.stringify(result));
+  process.exitCode = result.valid ? 0 : 1;
+}

package/templates/.agents/skills/zaip-skill-landing-page-forms/scripts/validate-plan.test.mjs

@@ -0,0 +1,183 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+import { validateFormPlan } from "./validate-plan.mjs";
+
+const read = async (name) =>
+  JSON.parse(await readFile(new URL(`../references/${name}.example.json`, import.meta.url)));
+for (const name of ["single-screen", "multistep", "contact-then-qualification"]) {
+  test(`accepts coherent synthetic ${name} without claiming live proof`, async () => {
+    const result = validateFormPlan(await read(name));
+    assert.deepEqual(result, {
+      valid: true,
+      issues: [],
+      scope: "plan_coherence_only",
+      live_verified: false,
+    });
+  });
+}
+const mutations = [
+  [
+    "missing server validation",
+    (p) => delete p.submission.server_validation,
+    "description_required",
+  ],
+  [
+    "timeout treated as final without reconciliation",
+    (p) => (p.submission.uncertain_reconciliation = ""),
+    "description_required",
+  ],
+  [
+    "navigation used as persistence",
+    (p) => (p.submission.navigation = "redirect-first"),
+    "navigation_is_not_persistence",
+  ],
+  [
+    "HTTP success used as confirmation",
+    (p) => (p.submission.confirmation = "http-2xx"),
+    "durable_confirmation_required",
+  ],
+  [
+    "all requests counted as new Leads",
+    (p) => (p.measurement.lead = "all-requests"),
+    "lead_semantics_required",
+  ],
+  [
+    "optional consent bundled with service",
+    (p) => (p.consents.marketing = "bundled"),
+    "separate_consent_required",
+  ],
+  [
+    "contact in persistent browser storage",
+    (p) => (p.recovery.storage = "localStorage"),
+    "contact_browser_storage_not_supported",
+  ],
+  [
+    "personal payload diagnostics",
+    (p) => (p.measurement.logs = "full-payload"),
+    "sensitive_logs_forbidden",
+  ],
+  [
+    "conditional orphan",
+    (p) => {
+      p.fields[1].conditional_on = "missing";
+      p.fields[1].when_hidden = "clear";
+    },
+    "invalid_condition_reference",
+  ],
+  [
+    "hidden values retained for submission",
+    (p) => (p.fields[1].conditional_on = "contact_email"),
+    "hidden_value_policy_required",
+  ],
+  [
+    "duplicate field identity",
+    (p) => (p.fields[1].id = p.fields[0].id),
+    "unique_field_id_required",
+  ],
+  ["undefined field identifier", (p) => delete p.fields[0].id, "unique_field_id_required"],
+  [
+    "blocked Escape",
+    (p) =>
+      (p.accessibility.dialog = {
+        escape: "blocked",
+        return_focus: "opener",
+        alternative_exit: "close button",
+      }),
+    "dialog_escape_required",
+  ],
+  [
+    "sensitive extra input",
+    (p) => (p.actual_contact = "synthetic-private-sentinel"),
+    "unknown_key",
+  ],
+  [
+    "missing uncertain state",
+    (p) => (p.states = p.states.filter((s) => s !== "uncertain")),
+    "submission_states_required",
+  ],
+];
+for (const [name, mutate, code] of mutations)
+  test(`rejects ${name}`, async () => {
+    const plan = await read("single-screen");
+    mutate(plan);
+    const result = validateFormPlan(plan);
+    assert.equal(result.valid, false);
+    assert(result.issues.some((issue) => issue.code === code));
+    assert(!JSON.stringify(result).includes("synthetic-private-sentinel"));
+  });
+test("contact qualification must follow contact and specify amend", async () => {
+  const plan = await read("contact-then-qualification");
+  plan.fields[1].step = plan.steps[0];
+  delete plan.submission.qualification_update;
+  const result = validateFormPlan(plan);
+  assert(result.issues.some((issue) => issue.code === "contact_then_qualification_order"));
+  assert(result.issues.some((issue) => issue.path === "submission.qualification_update"));
+});
+test("explicit minimized nonpersonal browser recovery is a supported decision", async () => {
+  const plan = await read("multistep");
+  plan.recovery.storage = "browser-minimized";
+  assert.equal(validateFormPlan(plan).valid, false);
+  plan.recovery.browser_data = "nonpersonal-only";
+  assert.equal(validateFormPlan(plan).valid, true);
+});
+test("measurement may be unused or use an explicitly versioned request policy", async () => {
+  const plan = await read("single-screen");
+  plan.measurement.lead = "not-used";
+  delete plan.measurement.policy_ref;
+  delete plan.measurement.policy_version;
+  assert.equal(validateFormPlan(plan).valid, true);
+  plan.measurement.lead = "approved-request-contract";
+  assert.equal(validateFormPlan(plan).valid, false);
+  plan.measurement.policy_ref = "business-request-contract";
+  plan.measurement.policy_version = 3;
+  assert.equal(validateFormPlan(plan).valid, true);
+});
+test("save points must name existing ordered stages and explicit persistence operations", async () => {
+  for (const mutate of [
+    (p) => p.persistence.save_points.reverse(),
+    (p) => (p.persistence.save_points[0].step = "missing"),
+    (p) => (p.persistence.save_points[0].trigger = "next-button"),
+    (p) => (p.persistence.save_points[0].receipt = "navigation"),
+    (p) => (p.persistence.save_points = []),
+    (p) => p.persistence.save_points.push(p.persistence.save_points[0]),
+  ]) {
+    const plan = await read("multistep");
+    mutate(plan);
+    assert.equal(validateFormPlan(plan).valid, false);
+  }
+});
+test("final persistence is not implied by first navigation and contact must precede amend", async () => {
+  const final = await read("multistep");
+  final.persistence = {
+    mode: "final",
+    save_points: [
+      {
+        step: "service",
+        kind: "final",
+        trigger: "explicit-submit",
+        receipt: "durable-server-receipt",
+      },
+    ],
+  };
+  assert.equal(validateFormPlan(final).valid, false);
+  final.persistence.save_points[0].step = "contact";
+  assert.equal(validateFormPlan(final).valid, true);
+  const contact = await read("contact-then-qualification");
+  contact.persistence.save_points.reverse();
+  assert(
+    validateFormPlan(contact).issues.some(
+      (issue) => issue.code === "registration_before_qualification",
+    ),
+  );
+});
+test("cyclic conditions and malformed structures fail without exceptions", async () => {
+  const plan = await read("single-screen");
+  plan.fields[0].conditional_on = plan.fields[1].id;
+  plan.fields[0].when_hidden = "clear";
+  plan.fields[1].conditional_on = plan.fields[0].id;
+  plan.fields[1].when_hidden = "clear";
+  assert(validateFormPlan(plan).issues.some((issue) => issue.code === "condition_cycle"));
+  for (const value of [null, [], false, {}, { fields: [null] }])
+    assert.equal(validateFormPlan(value).valid, false);
+});

package/templates/.agents/skills/zaip-skill-lead-measurement/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: zaip-skill-lead-measurement
+description: Implement or diagnose lead measurement contracts across backend acceptance, enum classification, consent, GTM, GA4, Google Ads and Meta when tracking registrations or later qualification.
+---
+
+# Implementar mensuração de leads
+
+Antes de implementar, leia [arquitetura e D-01](references/architecture.md), [autoridade e gates de adoção](references/authority.md) e [matriz de implementação e prova](references/implementation-plan.md). A entrada é descoberta do negócio com [Sales](../zaip-skill-sales-methodology/SKILL.md): questionário, regra comercial, recorrência e destinos precisam de aprovação por empresa. Exemplos não ativam regras. Cadastro, perfil completo e qualificação são fatos distintos.
+
+O pacote portável contém contratos, runbooks e um helper determinístico local. Não cria backend, adaptador produtivo, banco, conta ou configuração ativa. D-01 não bloqueia a documentação genérica; permanece obrigatória antes da adoção que dependa do banco. O schema v1 continua disponível; evolução v2 é opt-in e não autoriza reinterpretar histórico ou reenviar eventos.
+
+1. Defina o evento de negócio e a prova de persistência no backend. `lead_accepted` confirma cadastro; clique, submit e backend rejeitado são outros estados. `lead_qualified` posterior tem outra identidade e não recria a conversão primária.
+2. Fixe projeto/ambiente, recursos de destino, autorização, versões do catálogo/mapeamento e enums de classificação. Leia [contrato estrito](references/event-contract.md). Não use campos livres, dados de contato ou classificações inferidas de nomes de campanhas.
+3. Implemente o envelope interno no backend autorizado; o navegador recebe uma projeção após sucesso confirmado. Um `persisted:true` declarado pelo cliente não prova aceitação. Preserve a transação real lead/outbox quando possível e documente a lacuna se forem duas escritas independentes.
+4. Use [entrega e limites do helper](references/delivery-contract.md). O helper JavaScript é um modelo determinístico sem rede/DB: valida, projeta, modela dedupe/conflito e retry. Ele não instala uma outbox persistente, não envia eventos e não comprova consentimento nem identidade de conta.
+5. Execute os exemplos sintéticos locais:
+
+   ```sh
+   node .agents/skills/zaip-skill-lead-measurement/scripts/lead-measurement.mjs validate --event .agents/skills/zaip-skill-lead-measurement/references/synthetic-event.json --config .agents/skills/zaip-skill-lead-measurement/references/synthetic-config.json
+   node .agents/skills/zaip-skill-lead-measurement/scripts/lead-measurement.mjs project --event .agents/skills/zaip-skill-lead-measurement/references/synthetic-event.json --config .agents/skills/zaip-skill-lead-measurement/references/synthetic-config.json
+   node --test .agents/skills/zaip-skill-lead-measurement/scripts/lead-measurement.test.mjs
+   ```
+
+6. Escolha somente os destinos solicitados e implemente com suas skills: [GTM](../zaip-skill-google-tag-manager/SKILL.md), [GA4](../zaip-skill-google-analytics/SKILL.md), [Ads](../zaip-skill-google-ads-conversions/SKILL.md), [Meta](../zaip-skill-meta-conversions/SKILL.md). Execute instalação/configuração autorizadas; recursos externos sem autorização/acesso ficam com preparação concreta e passo pendente.
+7. Consentimento ausente vira `unknown`. Verifique a lista versionada de sinais exigidos por destino; negado/desconhecido não habilitam envio. Pings cookieless/Consent Mode são configuração própria, nunca fallback automático.
+8. Projete allowlists por destino. GA4 nunca recebe contato, hash de contato, texto livre, formulário ou recibo interno. Ads tem uma fonte primária escolhida. Pixel/CAPI usam o mesmo nome/ID da mesma aceitação. Congele versão, horário e conteúdo em reentregas.
+9. Integre dedupe por destino/ID em armazenamento real, recuse payload conflitante e limite retries de falhas transitórias com `Retry-After` válido. Falha de analytics preserva o cadastro aceito. Tokens de servidor usam o Infisical autorizado e não entram em evidências.
+10. Valide sucesso, rejeição, qualificação tardia, consentimento negado/desconhecido, replay, conflito e esgotamento de retry. Registre separadamente teste local, configuração externa, recebimento, deduplicação e atribuição/contabilização; não promova uma dessas provas às demais.
+
+Para CRM, componha [integrações externas](../zaip-skill-external-integrations/SKILL.md) e descoberta comercial; o exemplo Kommo desabilitado não comprova integração disponível. Preserve carteira, responsável, estágio, tags e decisões manuais. Paginação incompleta ou match ambíguo impedem concluir ausência e criar automaticamente.
+
+Compatibilidade não torna o helper uma prova de entrega: HTTP 2xx isolado não comprova aceite semântico, ingestão, deduplicação ou atribuição. A evolução do contrato deve corrigir ou depreciar explicitamente o caminho legado 2xx→sent por adaptador versionado; até lá, não o use como confirmação operacional. Falha após possível efeito exige reconciliação antes de repetir.

package/templates/.agents/skills/zaip-skill-lead-measurement/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Lead Measurement"
+  short_description: "Validate lead classification and delivery contracts"
+  default_prompt: "Use $zaip-skill-lead-measurement to define and verify consent, lead classification and idempotent event delivery."

package/templates/.agents/skills/zaip-skill-lead-measurement/references/architecture.md

@@ -0,0 +1,51 @@
+# Arquitetura portável de mensuração
+
+Contrato documental v1, revisão 2026-10-29. Responsável técnico: manutenção de lead-measurement; responsável pela adoção: técnico designado pela empresa, ainda não informado. Esta referência compõe capacidades existentes; não instala API, worker, adaptador, schema ou serviço.
+
+## Stack observada e decisão D-01
+
+Snapshot da fonte canônica `.agents/config/project.yaml`, SHA-256 `77806c330f9db2576f9406e40fef8d56bea94170c5b1a3912f9bafae84f324d6`, observado em 2026-10-29. Profile `zaip-aios-stack`, linguagem `typescript`, API `hono`, query builder `kysely`. As versões abaixo descrevem configuração declarada, sem comprovar instalação ou implantação.
+
+| Camada | Declaração exata relevante | Aplicação ao contrato |
+| --- | --- | --- |
+| Linguagem | TypeScript 7.0.2 | Tipos e contratos; domain sem I/O ou fornecedor |
+| Runtime | Node.js 24.19.0 | Composition roots futuras de API, dispatcher e worker |
+| API | Hono 4.13.11 | Rotas/middleware, validação e autorização de tenant |
+| Acesso a dados | Kysely 0.29.6 | Port de persistência e transações PostgreSQL autorizadas |
+| Banco atual declarado | PostgreSQL via Supabase — Serviço em nuvem | Contexto atual; major não informado, não é seleção para nova adoção |
+| Auth/Storage atuais | Supabase Auth + Storage — Serviço em nuvem | Contexto declarado, sem introduzir SDK, serviço ou dependência nova |
+| Cache/mensageria | Redis 6.2.1, referência `npm:redis` | Versão declarada do pacote cliente, não versão comprovada do servidor |
+| Fila | BullMQ 6.2.0 | Transporte recuperável de referências, nunca verdade comercial |
+| Credenciais | Infisical self-hosted | Referências opacas; nenhum cofre ou secret acessado |
+| Infra/backend | Terraform 1.16.1; Hostinger VPS — Serviço em nuvem | Contexto, sem provisionamento ou escolha de hospedagem nova |
+| App web | React 19.2.7; TypeScript 7.0.2; Vite 8.1.6; Cloudflare Pages | Descobrir superfície real antes de implementar |
+| Site | Astro 7.2.8; React Islands 19.2.7; TypeScript 7.0.2; Vite 8.1.6; Cloudflare Pages | Referência declarada, sem transplantar layout para consumidor |
+
+**D-01 permanece pendente.** O padrão atual declara Supabase; a restrição desta entrega proíbe introduzir Supabase novo, Edge Functions ou Database Webhooks. A solução documental conserva Node/TypeScript/Hono/Kysely e descreve PostgreSQL independente de provedor. PostgreSQL 16 é apenas o dialeto condicionado dos documentos de auditoria, nunca major encontrado, escolha aprovada ou autorização para upgrade. Não se escolheu provedor alternativo, major, empresa, role ou mecanismo de autenticação. Não copiar funções `api_meta` de consumidor.
+
+Antes da adoção, registrar banco existente, versão, schema, autenticação, roles, tenancy, compatibilidade e aprovação da adaptação/exceção à stack. Sem isso, não implementar persistência nem executar SQL. A documentação e os testes determinísticos sem DB podem prosseguir com D-01 aberta. Não editar project.yaml para disfarçar o conflito. Consulte os [gates de autoridade](authority.md).
+
+## Fronteiras e fluxo de referência
+
+Direção `apps -> modules -> packages`: `apps/backend` é composition root futura de API e workers; módulos possuem negócio/storage privado; packages fornecem mecanismos técnicos. `apps/site` e `apps/frontend`, quando existentes, consomem contratos públicos. Site não lê `.agents` nem importa dashboard. Este documento não cria diretórios de aplicação.
+
+| Componente futuro | Entrada e responsabilidade | Saída / condição de falha |
+| --- | --- | --- |
+| Domain | Ocorrência, avaliação, finalidade e regras versionadas aprovadas | Nenhum import de Hono, Kysely, Redis ou provedor |
+| Application | Commands de cadastro, complemento, qualificação, revogação e entrega; queries de recibo/diagnóstico | Ports explícitos; queries não publicam nem alteram estado |
+| API Hono | Resolve tenant/formulário/destinos no servidor; valida payload, idempotência e finalidade | Recibo público mínimo somente após commit; rejeição/incerteza não emite aceitação |
+| Persistência Kysely | Contato, ocorrência, avaliação, consentimento, evento e entrega; transação proposta | Rollback não emite recibo positivo; pool/contexto/roles exigem prova real futura |
+| Projeção browser | Mesmo evento e parâmetros allowlist após recibo elegível | Site → GTM → GA4/Ads; uma fonte Ads por ação; falha de tag preserva cadastro |
+| Dispatcher/scheduler | Lê pendências duráveis e publica referências | Redis/BullMQ transporta IDs sem contatos; repetição de job não cria outro fato |
+| Worker Node | Revalida destino, lease/fence, modo e consentimento vigente; carrega snapshot restrito | Adaptadores Meta CAPI/Kommo futuros validam resposta; timeout pós-efeito reconcilia |
+| Diagnóstico | IDs opacos, estado, código técnico e horário | Payload restrito e histórico comercial separados; sem token, contato ou hash pessoal |
+
+Fluxo condicionado: cadastro → transação ocorrência/evento/entregas → commit → recibo → projeção browser. Em paralelo, outbox durável → dispatcher → BullMQ → worker → adaptador → aceite semântico ou reconciliação. Nenhuma chamada HTTP dentro da transação; nenhum exactly-once global prometido. Lease por entrega e coordenação por contato/destino Kommo são fronteiras distintas.
+
+Google permanece browser-first. Measurement Protocol/backend Google é opcional e exige necessidade aprovada, contrato de identidade/consentimento e prova própria; não corrige trigger errado por default. Pixel/CAPI compartilham nome/ID do mesmo fato quando autorizados. Recebimento não equivale a conversão personalizada configurada nem atribuição.
+
+Contato, ocorrência, avaliação, evento e entrega têm identidades distintas, sempre sob tenant/ambiente/recurso/modo. Retry preserva ID, horário, payload e fingerprint; nova versão de mapping não autoriza replay. Perfil/qualificação referenciam a solicitação raiz e não multiplicam cadastro. Política de recorrência, BANT e match pertence à empresa; não há janela de 24h ou desqualificação por decisão compartilhada universais.
+
+## Limites da referência
+
+Componha [modelagem](../../zaip-skill-data-modeling/SKILL.md), [tenancy](../../zaip-skill-auth-tenancy/SKILL.md), [jobs](../../zaip-skill-async-jobs/SKILL.md), [migrações](../../zaip-skill-database-migrations/SKILL.md) e [observabilidade](../../zaip-skill-application-observability/SKILL.md) conforme impacto. A GUC de tenant não autentica; runtime não deve ser owner/BYPASSRLS. Constraints, concorrência, RLS, restore e atomicidade continuam sem prova DB nesta entrega. A [matriz](implementation-plan.md) indica a Task que detalha cada contrato, sem tratar documentos futuros como implementados.

package/templates/.agents/skills/zaip-skill-lead-measurement/references/authority.md

@@ -0,0 +1,49 @@
+# Autoridade, decisões e adoção
+
+Contrato documental v1, revisão 2026-10-29. O pacote portável pode ser entregue com decisões externas pendentes. Sua entrega não autoriza adoção: cada efeito exige alvo, capacidade, permissão e evidência próprios. Responsável pela adoção e aprovadores continuam não informados; não preencher a ficha com exemplos.
+
+## Limite desta entrega
+
+Permitidos somente os contratos/runbooks e helpers/fixtures determinísticos previstos na Task ativa, dentro dos seus scopes. C01 altera quatro documentos; não cria helper ou fixture. Nenhum SQL, inclusive SELECT local, PGlite, migration ou parse por banco; nenhuma conta real, leitura nova de consumidor, infraestrutura, secret, rede operacional, push, deploy ou release. Commit local canônico da Task segue a governança autorizada e não concede publicação. Nunca reiniciar, desligar, suspender, hibernar ou encerrar sessão do computador do usuário.
+
+Operações futuras aqui descritas são condições de adoção, não instrução para executá-las durante a entrega do pacote. Catálogo, ferramenta disponível, login, nome/ID de conta, fonte pública ou exemplo não concedem autoridade. Descobrir capacidade não prova autorização; permissão de um destino não se transfere para outro. Uma autorização de SQL/publicação/CRM/envio precisa cobrir a operação e o ambiente exatos.
+
+## Gates externos indispensáveis
+
+| Gate e responsável a designar | Informação / aprovação necessária | Bloqueia na adoção |
+| --- | --- | --- |
+| D-01 — técnico e proprietário do banco | Banco existente, provedor, major, schema, roles/auth, tenancy e exceção/adaptação explícita; PostgreSQL 16 apenas condicionado | Persistência, migração e integração que dependam desse banco |
+| Negócio — responsável comercial | Empresa/oferta, questionário e regra BANT versionados, recorrência, match, override, casos positivos/negativos/fronteira | Formulário, qualificação e transição CRM; fixture não substitui aprovação |
+| Privacidade — responsável designado | Contato/termos/analytics/Google Ads/Meta separados; origem, retenção, revogação e CMP efetiva | Loader/base/PageView e envio/retry sem finalidade elegível; unknown/denied não enviam |
+| Recursos — operador de cada conta | Tenant, ambiente, conta, recurso/dataset/pipeline/campos e destinos server-owned; inventário completo e permissão efetiva | Configuração e envio com destino divergente, desconhecido ou paginação incompleta |
+| Segurança — técnico/operador | Identidade de serviço, egress, acesso mínimo e secret delivery no cofre aprovado; sem valores em chat/log/browser | Credencial, integração ou acesso a payload restrito |
+| Dados — proprietário e revisor | Compatibilidade por SHA/contrato, plano expand/contract, backup/restore, retenção e autorização separada de SQL/backfill | Migration, reprocessamento ou alteração de dado/schema |
+| Fontes e versões — mantenedor do runbook | Documentação oficial/UI/API vigente, versão explícita, data e limitações; pendências Meta de 429 não resolvidas por suposição | Alegações de janela de dedupe, suporte Graph ou permissões não verificadas |
+| Ativação — operador autorizado | Draft, backup/diff revisado, concorrência, rollback, teste/prod separados e marco de ativação | Publicação de container, deploy, CRM write e eventos reais; sem backfill automático |
+| Operação — responsável técnico | Monitoramento, aging/terminal/reconciliação, SLO e procedimento de recuperação aprovados | Operação sustentada e declaração de prontidão |
+
+Consent Mode/default denied não prova ausência de pings; cookieless exige contrato próprio. Consentimento Google não concede Meta. Snapshot histórico não substitui estado vigente antes de envio/retry. Revogação não desfaz requisição já em voo; o limite deve constar da adoção.
+
+## Ficha de adoção — não preenchida
+
+Estado `draft`; sem escolha de empresa, provedor, major ou política comercial.
+
+| Campo | Valor atual |
+| --- | --- |
+| Empresa / oferta / tenant / ambientes / domínio | Não informado |
+| Responsável técnico / comercial / privacidade / operadores | Não informado |
+| D-01: banco / versão / auth / roles / schema / aprovação | Pendente |
+| Contrato técnico / questionário / regra / consentimento / mapping e vigências | Não aprovados |
+| Recorrência / match / override / retenção / volume e SLO | Não definidos |
+| Recursos Google / Meta / Kommo e permissões | Não descobertos para adoção |
+| Credenciais e identidades de serviço | Sem acesso; somente referências opacas futuras |
+| Autorizações SQL / backfill / CRM / envio / publicação | Não concedidas por este pacote |
+| Candidato / backup / teste isolado / rollback e provas por camada | Pendente de adoção específica |
+
+Pendências bloqueiam os efeitos correspondentes, sem impedir documentação genérica. Não ativar template draft, usar fixture como regra real, inferir permissões ou preencher unknown com defaults comerciais. Falta de ferramenta/acesso exige passo concreto pendente e responsável, sem contornar recusa.
+
+## Provas separadas e rollback
+
+Contrato revisado → teste local → navegador interceptado → DB isolado autorizado → Preview/DebugView → configuração publicada → envio/aceite API → evento visível → dedupe → conversão → atribuição/CRM correto são alegações distintas. Executar uma camada não aprova a próxima. SQL e contas permanecem fora do pacote; não registrar ausência de acesso como reprovação do produto ou sucesso operacional.
+
+Rollback de C01 reverte apenas seu diff documental, preservando histórico e trabalho alheio. Rollback futuro de adoção pausa claims/tags novos, reconcilia efeitos incertos e mantém IDs/snapshots/vínculos; não apaga fila, contato, evento aceito ou histórico para reenviar. Reversão DB e compensação comercial exigem plano e autorização próprios. Consulte [arquitetura](architecture.md) e [matriz de prova](implementation-plan.md).