@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-meta-conversions/scripts/meta-model.test.mjs

@@ -0,0 +1,394 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { test } from "node:test";
+import {
+  createMetaSimulation,
+  matchesConversion,
+  pairInvariant,
+  productionCutover,
+  semanticReceipt,
+} from "./meta-model.mjs";
+
+const fixture = JSON.parse(
+  await readFile(new URL("../references/synthetic-meta.json", import.meta.url), "utf8"),
+);
+const event = JSON.parse(
+  await readFile(
+    new URL("../../zaip-skill-lead-measurement/references/synthetic-event.json", import.meta.url),
+    "utf8",
+  ),
+);
+const config = JSON.parse(
+  await readFile(
+    new URL("../../zaip-skill-lead-measurement/references/synthetic-config.json", import.meta.url),
+    "utf8",
+  ),
+);
+const fresh = () => structuredClone(fixture);
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+function setup(
+  f = fresh(),
+  initial = [{ purpose: "meta_measurement", state: "granted", sequence: 1 }],
+) {
+  let history = initial;
+  const seen = [];
+  const model = createMetaSimulation({
+    policy: f.policy,
+    measurement_config: config,
+    readCurrent: () => {
+      if (history instanceof Error) throw history;
+      return history;
+    },
+  });
+  const effects = Object.fromEntries(
+    ["load", "public", "restricted", "log"].map((kind) => [
+      kind,
+      (value) => seen.push({ kind, value }),
+    ]),
+  );
+  const request = (phase = "event", e = structuredClone(event)) => ({
+    phase,
+    event: e,
+    client: {},
+    private_matching: structuredClone(f.private_email),
+  });
+  return {
+    model,
+    effects,
+    seen,
+    request,
+    set: (next) => {
+      history = next;
+    },
+  };
+}
+function productionPolicy() {
+  const f = fresh();
+  f.policy.test_mode = false;
+  f.policy.environment = "production";
+  delete f.policy.test_event_code;
+  return f;
+}
+function cutoverFixture() {
+  const f = productionPolicy(),
+    run = setup(f),
+    e = structuredClone(event);
+  e.event_id = "evt_synthetic_new_production";
+  e.occurred_at = "2026-10-29T13:00:00Z";
+  assert.equal(run.model.attempt(run.request("event", e), run.effects).allowed, true);
+  const restricted = run.seen.find((item) => item.kind === "restricted").value;
+  const activation = Date.parse(e.occurred_at);
+  return {
+    approved_target: { tenant: f.policy.tenant, dataset_id: f.policy.dataset_id },
+    effective_config: f.policy,
+    payloads: [structuredClone(restricted)],
+    activation_ms: activation,
+    existing_event_ids: ["evt_synthetic_existing_fact"],
+    prior_test_event_ids: [event.event_id],
+    jobs: [
+      {
+        origin_mode: "production",
+        test_mode: false,
+        dataset_id: f.policy.dataset_id,
+        event_id: e.event_id,
+        created_ms: activation,
+        state: "new",
+        payload: structuredClone(restricted.payload),
+      },
+    ],
+  };
+}
+
+test("server-owned dataset and same Pixel/CAPI name-ID; private matching stays private", () => {
+  const f = setup();
+  assert.equal(f.model.attempt(f.request(), f.effects).allowed, true);
+  const pub = f.seen.find((item) => item.kind === "public").value;
+  const restricted = f.seen.find((item) => item.kind === "restricted").value;
+  assert.deepEqual(pairInvariant(pub.pixel, restricted), {
+    same_fact: true,
+    deduplication_observed: false,
+    dedupe_window_verified: false,
+  });
+  assert.equal(restricted.payload.user_data.em[0], hash("lead@example.invalid"));
+  assert.equal(restricted.payload.test_event_code, fixture.policy.test_event_code);
+  for (const item of f.seen.filter((item) => item.kind !== "restricted")) {
+    assert.doesNotMatch(
+      JSON.stringify(item.value),
+      /lead@example|receipt_|TEST_SYNTHETIC|user_data|private_matching/i,
+    );
+    assert.equal(JSON.stringify(item.value).includes(hash("lead@example.invalid")), false);
+  }
+  assert.equal(pub.pixel.eventID, event.event_id);
+  assert.equal(pub.pixel.event_name, "Lead");
+  assert.equal(pub.url, "https://example.invalid/lead");
+});
+test("client cannot choose another dataset; two approved server targets remain distinct", () => {
+  const f = setup();
+  assert.throws(() =>
+    f.model.attempt({ ...f.request(), client: { dataset_id: "synthetic_dataset_b" } }, f.effects),
+  );
+  assert.equal(f.seen.length, 0);
+  const other = fresh();
+  other.policy.dataset_id = "synthetic_dataset_b";
+  const b = setup(other);
+  assert.equal(b.model.attempt(b.request(), b.effects).allowed, true);
+  assert.equal(
+    b.seen.find((item) => item.kind === "restricted").value.target.dataset_id,
+    "synthetic_dataset_b",
+  );
+  const first = setup();
+  first.model.attempt(first.request(), first.effects);
+  const pixel = first.seen.find((item) => item.kind === "public").value.pixel;
+  assert.throws(
+    () => pairInvariant(pixel, b.seen.find((item) => item.kind === "restricted").value),
+    /mismatch/,
+  );
+});
+test("matching uses explicit country code, no double-hash and only approved fields", () => {
+  const f = fresh();
+  f.policy.matching_fields = ["phone"];
+  const run = setup(f);
+  assert.equal(
+    run.model.attempt({ ...run.request(), private_matching: f.private_phone }, run.effects).allowed,
+    true,
+  );
+  assert.equal(
+    run.seen.find((item) => item.kind === "restricted").value.payload.user_data.ph[0],
+    hash("12025550123"),
+  );
+  for (const matching of [
+    { email: hash("lead@example.invalid") },
+    { email: "lead@example.invalid", phone: "+12025550123" },
+    { em: hash("lead@example.invalid") },
+    { fbc: "fabricated" },
+    {},
+  ]) {
+    const denied = setup();
+    assert.equal(
+      denied.model.attempt({ ...denied.request(), private_matching: matching }, denied.effects)
+        .allowed,
+      false,
+    );
+    assert.equal(denied.seen.length, 0);
+  }
+  const badPhone = setup(f);
+  assert.equal(
+    badPhone.model.attempt(
+      { ...badPhone.request(), private_matching: { phone: "2025550123" } },
+      badPhone.effects,
+    ).allowed,
+    false,
+  );
+});
+test("unknown denied revoked and Google-only consent block every phase and matching", () => {
+  for (const state of ["unknown", "denied", "revoked"])
+    for (const phase of ["loader", "base", "page_view", "event", "retry"]) {
+      const f = setup(fresh(), [{ purpose: "meta_measurement", state, sequence: 1 }]);
+      assert.equal(f.model.attempt(f.request(phase), f.effects).allowed, false);
+      assert.equal(f.seen.length, 0);
+    }
+  const f = setup(fresh(), [{ purpose: "google_ads", state: "granted", sequence: 1 }]);
+  assert.equal(f.model.attempt(f.request(), f.effects).allowed, false);
+  assert.equal(f.seen.length, 0);
+});
+test("already-loaded Pixel and retry recheck current revocation, failure and regrant", () => {
+  const f = setup();
+  assert.equal(f.model.attempt(f.request("loader"), f.effects).allowed, true);
+  assert.equal(f.model.attempt(f.request("loader"), f.effects).status, "already_loaded");
+  const before = f.seen.length;
+  f.set([{ purpose: "meta_measurement", state: "revoked", sequence: 2 }]);
+  for (const phase of ["loader", "base", "page_view", "retry"])
+    assert.equal(f.model.attempt(f.request(phase), f.effects).allowed, false);
+  assert.equal(f.seen.length, before);
+  f.set(new Error("synthetic_private@example.invalid"));
+  assert.deepEqual(f.model.attempt(f.request(), f.effects), {
+    allowed: false,
+    reason: "consent_ineligible",
+  });
+  f.set([{ sequence: 1, state: "granted", purpose: "meta_measurement" }]);
+  assert.equal(f.model.attempt(f.request(), f.effects).allowed, false);
+  f.set([{ sequence: 3, state: "granted", purpose: "meta_measurement" }]);
+  assert.equal(f.model.attempt(f.request("retry"), f.effects).allowed, true);
+});
+test("strict records reject getters symbols and nonenumerables before effects", () => {
+  const f = setup();
+  let calls = 0;
+  const e = structuredClone(event);
+  Object.defineProperty(e, "event_id", {
+    enumerable: true,
+    get() {
+      calls++;
+      return event.event_id;
+    },
+  });
+  assert.throws(() => f.model.attempt(f.request("event", e), f.effects));
+  assert.equal(calls, 0);
+  assert.equal(f.seen.length, 0);
+  const hidden = f.request();
+  Object.defineProperty(hidden.private_matching, "email", {
+    value: "lead@example.invalid",
+    enumerable: false,
+  });
+  assert.throws(() => f.model.attempt(hidden, f.effects));
+  assert.equal(f.seen.length, 0);
+  const symbolic = f.request();
+  symbolic[Symbol("private")] = "hidden";
+  assert.throws(() => f.model.attempt(symbolic, f.effects));
+  assert.equal(f.seen.length, 0);
+});
+test("property ordering is not semantic; dataset and URL/inventory divergence fail closed", () => {
+  const f = fresh(),
+    reordered = Object.fromEntries(Object.entries(f.policy).reverse());
+  const a = setup(f),
+    b = setup({ ...f, policy: reordered });
+  a.model.attempt(a.request(), a.effects);
+  b.model.attempt(b.request(), b.effects);
+  assert.deepEqual(a.seen, b.seen);
+  for (const change of [
+    (policy) => {
+      policy.dataset_id = "synthetic_unknown";
+    },
+    (policy) => {
+      policy.public_url += "?email=synthetic%40example.invalid";
+    },
+    (policy) => {
+      policy.inventory.loaders.push("duplicate_loader");
+    },
+  ]) {
+    const other = fresh();
+    change(other.policy);
+    assert.throws(() => setup(other));
+  }
+});
+test("qualified event preserves separate identity; shared authority is not a universal CRM rule", () => {
+  assert.equal(fixture.authority_context, "shared");
+  const f = setup(),
+    e = structuredClone(event);
+  e.event_id = "evt_synthetic_qualified_meta";
+  e.event_name = "lead_qualified";
+  e.classification.qualification = "qualified";
+  assert.equal(f.model.attempt(f.request("event", e), f.effects).allowed, true);
+  const pub = f.seen.find((item) => item.kind === "public").value;
+  assert.equal(pub.pixel.event_name, "QualifiedLead");
+  assert.equal(pub.pixel.eventID, e.event_id);
+  assert.equal(matchesConversion(pub.pixel.parameters, fixture.custom_conversion_rule), true);
+  assert.equal(
+    matchesConversion(
+      { ...pub.pixel.parameters, qualification: "new" },
+      fixture.custom_conversion_rule,
+    ),
+    false,
+  );
+  const profile = setup(),
+    input = structuredClone(event);
+  input.event_name = "lead_profile_completed";
+  assert.equal(
+    profile.model.attempt(profile.request("event", input), profile.effects).allowed,
+    false,
+  );
+  assert.equal(profile.seen.length, 0);
+});
+test("retry preserves name ID time matching snapshot; changing fact on the same ID is refused", () => {
+  const f = setup();
+  assert.equal(f.model.attempt(f.request(), f.effects).allowed, true);
+  const original = f.seen.find((item) => item.kind === "restricted").value;
+  assert.equal(f.model.attempt(f.request("retry"), f.effects).allowed, true);
+  assert.deepEqual(f.seen.filter((item) => item.kind === "restricted").at(-1).value, original);
+  const before = f.seen.length,
+    changed = structuredClone(event);
+  changed.event_name = "lead_qualified";
+  assert.equal(f.model.attempt(f.request("event", changed), f.effects).allowed, false);
+  assert.equal(f.seen.length, before);
+});
+test("production cutover accepts only fresh production material and leaves test history intact", () => {
+  const state = cutoverFixture(),
+    original = structuredClone(state);
+  assert.deepEqual(productionCutover(state), {
+    ready: true,
+    model_only: true,
+    test_jobs_promoted: false,
+    backfill: false,
+    deployment_verified: false,
+  });
+  assert.deepEqual(state, original);
+});
+test("test code must be absent from effective config, payload and nested queue material", () => {
+  for (const place of ["config", "payload", "job"])
+    for (const code of ["TEST_SYNTHETIC_ONLY", "", null]) {
+      const state = cutoverFixture();
+      const target =
+        place === "config"
+          ? state.effective_config
+          : place === "payload"
+            ? state.payloads[0].payload
+            : state.jobs[0].payload;
+      target.test_event_code = code;
+      assert.throws(() => productionCutover(state));
+    }
+});
+test("literal false mode, no promotion of test jobs, no relabelled test IDs or backfill", () => {
+  for (const change of [
+    (state) => {
+      state.effective_config.test_mode = "false";
+    },
+    (state) => {
+      state.payloads[0].target.test_mode = true;
+    },
+    (state) => {
+      state.jobs[0].test_mode = true;
+    },
+    (state) => {
+      state.jobs[0].origin_mode = "test";
+    },
+    (state) => {
+      state.jobs[0].created_ms = 99;
+    },
+    (state) => {
+      state.prior_test_event_ids.push(state.jobs[0].event_id);
+    },
+    (state) => {
+      state.existing_event_ids.push(state.jobs[0].event_id);
+    },
+    (state) => {
+      state.payloads[0].payload.event_time = Math.floor(state.activation_ms / 1000) - 1;
+    },
+    (state) => {
+      state.effective_config.dataset_id = "synthetic_dataset_b";
+      state.payloads[0].target.dataset_id = "synthetic_dataset_b";
+      state.jobs[0].dataset_id = "synthetic_dataset_b";
+    },
+    (state) => {
+      state.jobs[0].dataset_id = "synthetic_dataset_b";
+    },
+  ]) {
+    const state = cutoverFixture();
+    change(state);
+    assert.throws(() => productionCutover(state));
+  }
+});
+test("semantic receipt is normalized: malformed/202/2xx alone never proves ingestion or dedupe", () => {
+  for (const body of [{}, { events_received: 0 }, { events_received: "1" }]) {
+    let result;
+    try {
+      result = semanticReceipt({ status: 200, error: null, effect: "possible", body });
+    } catch {
+      result = { state: "uncertain" };
+    }
+    assert.notEqual(result.state, "confirmed");
+  }
+  assert.equal(
+    semanticReceipt({ status: 202, error: null, effect: "possible", body: {} }).state,
+    "queued",
+  );
+  const result = semanticReceipt({
+    status: 200,
+    error: null,
+    effect: "possible",
+    body: { events_received: 1 },
+  });
+  assert.equal(result.state, "confirmed");
+  assert.equal(result.ingestion_confirmed, false);
+  assert.equal(result.deduplication_observed, false);
+  assert.equal(result.attributed, false);
+});

package/templates/.agents/skills/zaip-skill-performance-engineering/SKILL.md

@@ -1,14 +1,39 @@
 ---
 name: zaip-skill-performance-engineering
-description: Measure and improve application latency, throughput, queries, queues, and resource use under stated conditions.
+description: Measure site performance and analyze Lighthouse or network reports, or improve application latency, throughput, queries and resources under stated conditions.
 ---
 
 # Engineer performance
 
 Use for a demonstrated latency, capacity, query, memory, or queue throughput concern.
+For sites/LPs choose `audit` (read-only), `create` (budgets before implementation), `fix`
+(measure baseline first), or `publication-check` after separately authorized deployment.
+
+Site/LP creation automatically composes [the site workflow](references/site-performance.md)
+from website-readiness, preserving design and conversion. Existing-site optimization
+measures before edits; a report-analysis request stays read-only. Use project-owned
+budgets and distinguish lab scores, transfer measurements and field CWV.
+For creation apply [Astro + React Islands](references/astro-islands.md); for Google
+reports use [metric diagnostics](references/google-diagnostics.md). Target Performance
+at least 91 independently on mobile and desktop, aiming at 95 for headroom. Preserve
+the project stack on existing sites; no framework or measured score is a guarantee.
+Load [third-party performance](references/third-party-performance.md) whenever GTM,
+analytics, Pixel or other external scripts affect the journey.
+Use [report import and gates](references/report-contract.md) for real Lighthouse/PSI
+JSON, equivalent 3/5-run comparisons and staged acceptance. Use the already installed
+Lighthouse [isolated runner](references/controlled-runner.md) only for a reviewed local
+static preview. No automatic install, account, upload, database or deployment is granted.
+GTmetrix/Pingdom exports remain manual/unsupported unless their real format is supported;
+do not relabel their grades as Lighthouse scores. Missing evidence is never a zero or pass.
 
 1. Define workload, data shape, environment, target metric, baseline, and success threshold before tuning.
 2. Profile the likely bottleneck across browser, API, database, cache, worker, and network boundaries before changing code.
 3. Change one justified cause at a time and preserve correctness, tenant isolation, and failure handling.
 4. Compare before and after under equivalent conditions using k6, autocannon, or a project-supported tool where appropriate.
 5. Report confidence limits, saturation behavior, and unmeasured production differences.
+
+For SEO/GEO changes, inspect initial HTML, hydrated DOM, mobile/navigation and third-party
+requests only where affected. Reuse image optimization and current stack. Lab timing,
+field CWV, crawler access and search visibility are separate observations; none guarantees
+ranking or warrants an automatic framework migration. Sources and applicability belong
+in the [website evidence contract](../zaip-skill-website-readiness/references/search-evidence.md).

package/templates/.agents/skills/zaip-skill-performance-engineering/references/astro-islands.md

@@ -0,0 +1,41 @@
+# Astro + React Islands desde a criação
+
+Use a stack de site configurada: Astro + TypeScript e React Islands é o padrão ZAIP.
+Leia versões/lockfile e a integração `@astrojs/react` compatível antes de escolher APIs.
+Não transforme otimização em upgrade de dependências ou migração implícita de consumidor.
+Para migração autorizada, componha [refactor-landing-page](../../zaip-skill-refactor-landing-page/SKILL.md).
+
+1. Mapeie conteúdo, layout, SEO e LCP para HTML gerado pelo Astro. Use geração estática
+   onde possível; SSR precisa de necessidade real e medição de cache/TTFB. Não embrulhe
+   a página inteira em uma raiz React hidratada nem duplique páginas por viewport.
+2. Liste cada ilha, função interativa, tamanho/CPU e prazo de disponibilidade. React
+   renderizado sem diretiva client gera HTML sem hidratação; use-o para conteúdo estático.
+   Não entregue um controle aparentemente funcional sem seus handlers necessários.
+3. Escolha hidratação por necessidade, não só posição:
+
+| Necessidade | Estratégia e prova |
+| --- | --- |
+| Formulário/menu que deve responder imediatamente | `client:load` na menor ilha necessária; testar clique/digitação imediatos em CPU lenta |
+| Interação dispensável no carregamento inicial | `client:idle`; timeout suportado e justificado quando houver prazo; medir tarefas após load |
+| Componente pesado abaixo da dobra | `client:visible` e margem quando útil; testar scroll rápido, teclado e foco antes da hidratação |
+| Conteúdo/hero essencial | HTML inicial; não usar `client:only` nem depender de fetch/hidratação para aparecer |
+
+4. Componentize sem criar uma ilha por elemento nem repetir bibliotecas/estado global.
+   Confira chunks, dependências transitivas, CSS utilizado e custo de hidratação real.
+   Prefetch, transições e scripts persistentes são opcionais: medir tráfego adicional,
+   remoção de listeners e page_view único em navegação, retorno e restauração do histórico.
+5. Use o pipeline de imagens do Astro quando compatível, compondo image-optimization:
+   srcset/sizes, dimensões e crop corretos, prioridade apenas no LCP; não lazy-load hero.
+   Fontes mantêm a tipografia aprovada, poucos pesos, fallback estável e preload medido.
+6. Compare screenshots mobile/desktop, HTML sem JS e após hidratação, teclado/foco,
+   envio imediato e erros de rede em sandbox. Preserve contrato do formulário, parâmetros
+   de atribuição e conversão confirmada no backend. Nenhuma otimização autoriza novas
+   seções/CTAs, remoção de conteúdo ou mudança de consentimento.
+7. Execute o build real e gates de [report-contract](report-contract.md) por rota,
+   dispositivo e cenário. Mínimo Performance 91; objetivo 95 para margem. Isso é política
+   ZAIP, não garantia da stack. Registre ausência de medição em vez de afirmar uma nota.
+
+Fontes oficiais verificadas em 2026-11-01; revalidar recursos contra a versão instalada:
+- https://docs.astro.build/en/concepts/islands/
+- https://docs.astro.build/en/reference/directives-reference/#client-directives
+- https://docs.astro.build/en/guides/images/

package/templates/.agents/skills/zaip-skill-performance-engineering/references/controlled-runner.md

@@ -0,0 +1,38 @@
+# Controlled Lighthouse sample
+
+`node .agents/skills/zaip-skill-performance-engineering/scripts/run-lighthouse.mjs CONFIG.json`
+uses already installed Lighthouse, chrome-launcher and Chrome. Missing dependencies return
+capability_missing/exit 6; there is no auto-install, upload or account use. No fake version
+is pinned: each real report records the actual Lighthouse version and browser user agent.
+
+Config: `confirm_isolated_preview:true`, exact `candidate_sha`, relative `site_directory`
+of reviewed static output, `form_factor:mobile|desktop`, `timeout_ms:5000..120000`.
+Optional dependency_root and chrome_path select explicitly reviewed installed tools on
+the host; never commit personal paths. Optional consent and expected_tags identify what
+the isolated scenario omits. The runner measures one sample per call, not a complete
+series. Keep and review its raw report_path; aggregate equivalent runs with assess-reports.
+Optional preview_port reserves the same explicit loopback port across separate calls;
+use it for a comparable series because the requested URL is part of configuration.
+Ephemeral default ports are useful for a single sample, not interchangeable URLs.
+
+An owned loopback static server/proxy allows only same-origin GET/HEAD of bounded files,
+rejects links, external origins, CONNECT, WebSocket upgrades and writes. Chrome uses this
+proxy and a fresh launcher-owned profile; finally closes its owned browser and server,
+including measurement deadline/failure. Reports use unique private .agents/private/state/site-performance
+directories and do not overwrite prior evidence. No unknown browser/process is killed.
+This is a tool boundary, not an OS sandbox against a hostile browser or local race.
+
+`external_policy:blocked` and `representative:false` are explicit. Do not convert an
+isolated result into production experience by declaration alone. If no external tags are
+expected, the host may independently verify the fixture matches that scoped journey.
+For a real consent/tag journey, use separately authorized representative Lighthouse/PSI
+collection and import its raw report with exact settings and expected tags. No need to
+weaken this runner or capture-site's blocking controls. Authentication, visual inspection,
+conversion behavior and field observations remain separate evidence.
+
+Creation/optimization references (host reviewed 2026-10-29):
+- https://web.dev/articles/optimize-lcp
+- https://web.dev/articles/optimize-inp
+- https://web.dev/articles/optimize-cls
+- https://web.dev/articles/font-best-practices
+- https://web.dev/articles/efficiently-load-third-party-javascript

package/templates/.agents/skills/zaip-skill-performance-engineering/references/google-diagnostics.md

@@ -0,0 +1,46 @@
+# Diagnóstico Google: score, gargalos e evidência
+
+A página About PSI é uma visão geral, não uma lista exaustiva de implementação.
+Leia os audits/Insights reais da versão usada e confira disponibilidade e unidades.
+Não transforme cada oportunidade em obrigação universal nem some economias estimadas
+como ganho garantido. TTI/FID históricos não são gates atuais obrigatórios.
+
+| Sinal | Investigação e ação guiada pela medição |
+| --- | --- |
+| TTFB | Separar redirects, DNS/conexão/TLS, cache e processamento do documento; evitar cadeias e cache inseguro de HTML personalizado |
+| LCP | Decompor TTFB, atraso de descoberta, duração de download e atraso de renderização; HTML inicial, prioridade e recurso adequados ao viewport |
+| FCP / Speed Index | CSS bloqueante, fontes, caminho crítico e progresso visual; confirmar no filmstrip, sem esconder conteúdo para obter nota |
+| TBT / CPU / INP | Parsing, hidratação e long tasks; separar atraso de entrada, processamento e apresentação; fracionar trabalho e medir formulário/cliques reais |
+| CLS | Dimensões de mídia/embeds, placeholders, fontes/fallback e conteúdo inserido; inspecionar scroll e estados, não só captura inicial |
+| Transferência / cache | Duplicatas, JS/CSS não usados, compressão Brotli/gzip suportada e cache de assets hashados; HTML tem política própria |
+
+Preload/preconnect só para recursos críticos comprovados; excesso disputa banda/CPU.
+Uma conexão a terceiro também pode ter implicações de consentimento. Meça cold e warm
+separadamente. Evite bibliotecas completas para uma função, layout thrashing e DOM
+desnecessário sem sacrificar semântica, acessibilidade, conteúdo ou aparência.
+
+Lighthouse calcula o score com métricas ponderadas conforme versão. Consulte auditRefs
+e documentação, sem fixar pesos no gate; diagnósticos não são uma soma de pontos.
+O Google classifica 90–100 como bom; ZAIP exige mínimo 91 para o pedido "acima de 90"
+e mira 95 para margem. Mobile e desktop têm séries próprias; não tirar média entre eles.
+
+O importador mantém FCP/Speed Index numéricos de lab e `server_response_ms` separado:
+`server-response-time` não representa todo o TTFB da navegação. TTFB de campo, quando
+presente em PSI CrUX, usa seu percentile; não derivar de LCP nem preencher ausência.
+FCP e TTFB de campo são diagnósticos complementares, não substituem LCP/INP/CLS.
+
+Dados de campo agregam experiências de 28 dias, p75 e escopo URL/origem/dispositivo;
+não comprovam isoladamente o efeito de um deploy recente. Ausência pode indicar falta
+de amostras. Google anunciou retirada de CrUX da API PSI: não depender desses campos
+para sempre. CrUX API/History são alternativas oficiais, mas respostas desses formatos
+ainda exigem revisão manual ou um adaptador explicitamente implementado e testado;
+não renomear seu JSON como PSI nem afirmar suporte automático inexistente.
+
+Fontes oficiais verificadas em 2026-11-01:
+- https://developers.google.com/speed/docs/insights/v5/about
+- https://developers.google.com/speed/docs/insights/v5/get-started
+- https://developer.chrome.com/docs/lighthouse/performance/performance-scoring
+- https://web.dev/articles/optimize-lcp
+- https://web.dev/articles/optimize-inp
+- https://web.dev/articles/optimize-cls
+- https://web.dev/articles/ttfb

package/templates/.agents/skills/zaip-skill-performance-engineering/references/report-contract.md

@@ -0,0 +1,99 @@
+# Report import, comparison and stage gates
+
+CrUX URL identity must equal the audited final URL, and origin identity must be exactly
+that URL's origin without a path. When requested/final differ and field data exists,
+declare `context.redirect:{requested_url,final_url,field_url:"requested"|"final"}` with
+the exact LHR URLs. Field data binds only to the selected URL/origin. A redirect without
+field data needs no mapping. This declaration explains the mapping; it does not
+authenticate a redirect or confer authority to another site.
+
+Deduplication uses `semantic_sample_sha256` of the canonical LHR, including fetchTime
+and audits. Whitespace, object-key order and PSI wrapper differences cannot turn the
+same LHR into independent samples. `raw_sha256` retains canonical report integrity;
+`file_sha256` separately records exact imported bytes. None authenticates authorship.
+
+Every result names its requested/final URL, candidate, device, tool version and browser
+environment fingerprint. Geography absent from the report stays unavailable. One series
+approves only one route/device; evaluate applicable mobile and desktop separately.
+`field_scope:url` is default; `origin` selects origin deliberately and `origin-fallback`
+uses it only when URL samples lack the metrics required by the project. All observations
+remain visible. A good URL does not inherit a failing origin. A ZAIP policy requiring
+all three CWV is distinct from whether a provider can assess its available metrics.
+
+`node .agents/skills/zaip-skill-performance-engineering/scripts/assess-reports.mjs CONFIG.json`
+reads a bounded local configuration and real Lighthouse LHR or PSI v5 response JSON.
+Paths are relative, traversal/nonfiles/links rejected. No URL fetch, report execution or
+upload occurs. URLs with credentials, query or fragment are rejected to avoid sensitive
+output. Source reports remain private: they may contain screenshots/DOM/network details.
+Only normalized metrics, hashes and declared conditions are returned; exceptions use a
+fixed sanitized code. A hash is integrity, not authentication of the report or author.
+
+Config schema 1: `before` and `after` arrays of at most ten `{path,context}` entries.
+Each context contains candidate_sha (exact Git SHA), scenario (`isolated|representative`),
+consent (scenario label), tags (expected identifiers), cache, external_policy
+(`blocked|authorized-import`). Keep labels free of account/contact/token information.
+The raw LHR supplies tool version, fetchTime, requested/final URL, form factor, screen,
+throttling and audits. Comparison binds that configuration plus tags/consent/cache;
+device or tool/version changes invalidate comparison. Do not silently change budgets.
+
+Copy [site-budgets.json](site-budgets.json) into project-owned config and adapt with
+reason/owner. Put it in `budgets` with `lab`, `scores`, `field_p75`,
+`max_variation_ratio` and `regression_ratio`; values must be finite nonnegative numbers.
+`absolute_tolerance` sets metric-specific noise floors; defaults CLS .01, TBT 50ms,
+LCP 100ms, JavaScript CPU 50ms, transfer 1024 bytes and scores 2 points are ZAIP
+conventions, not Google thresholds. Variation/regression must exceed both absolute and
+relative tolerance; absolute budget violations remain independent.
+The gate uses real numeric audits, not displayed strings or caller-declared scores.
+The default project template retains all four category targets; explicit project changes
+require owner/rationale rather than silently dropping a category. Thresholds are project
+goals, not guaranteed scores or accessibility conformance.
+`lcp_ms`, `tbt_ms` and `js_cpu_ms` are milliseconds; `cls` is dimensionless; scores are
+0–100. `bytes` is Lighthouse total-byte-weight for that measured navigation (network
+transfer), not build-directory raw/uncompressed size, not CDP initial/full-scroll totals.
+Never compare those different phases/origins as one metric. The legacy bytes budgets
+remain separately named; their old 250k JS target is not a raw dist-size allowance.
+`bootup-time` is Lighthouse's JavaScript CPU diagnostic, not a complete CPU profile.
+Diagnostic lab metrics `fcp_ms`, `speed_index_ms` and `server_response_ms` use numeric
+audits first-contentful-paint, speed-index and server-response-time, respectively.
+Missing/non-numeric values stay null; display strings are never parsed. Server response
+is not full navigation TTFB. PSI field FCP/TTFB retain their separate p75 provenance
+from FIRST_CONTENTFUL_PAINT_MS and EXPERIMENTAL_TIME_TO_FIRST_BYTE when present.
+These diagnostics are optional unless the project explicitly adds a required budget.
+Defaults require Performance >=91 per device, aiming for 95; do not round 90.x up
+to 91 or average mobile and desktop. A five-run median at 91 meets the numeric minimum;
+three near-threshold samples remain pending. Other category targets remain 95.
+
+Collect three equivalent independent raw reports per side. Exact duplicates are rejected.
+For large variation or a median within 5% of a budget, collect five deliberately. Five
+does not erase instability: excessive range remains pending for investigation. Output
+keeps every sample, median, min/max and range, plus CPU/LCP regressions even if bytes fall.
+
+| stage | Required proof | Missing data |
+| --- | --- | --- |
+| prepublication | Three/five equivalent lab reports and project budgets | pending, exit 6 |
+| public | Above plus separately observed published SHA/URL | pending until host observation reviewed |
+| field | Above and field p75 with scope/device/window | pending, never invented zero |
+
+`publication` is a reviewed host-observation locator `{candidate_sha,url,verified:
+"host_observation"}`; its JSON is not authenticated proof or deployment permission.
+The host must attach actual independent artifact/URL evidence. A caller can fabricate
+an imported report or declaration; this offline tool cannot attest authorship or deployment.
+Status `passed_scoped` (exit 0) means imported measurements satisfy this declared gate;
+`failed` exits 1; `pending` exits 6; malformed input exits 1 without raw paths/payloads.
+
+PSI Lighthouse lab and CrUX field are distinct. URL and origin experiences are retained
+separately, device/form factor and p75 recorded. `context.field_period:{start,end}` is
+required when adopting field evidence and marked caller-declared, not invented as a PSI
+response field. Missing INP is missing; lab TBT cannot substitute. `field_policy:observe`
+permits prepublication of a new site without field; `required` keeps that gate pending.
+GTmetrix grade/performance/structure and Pingdom grade/time remain provider-specific
+manual evidence; unsupported exports cannot satisfy the automatic lab gate.
+
+Official references, reviewed by the host for this work (2026-10-29):
+- https://developers.google.com/speed/docs/insights/v5/about
+- https://developer.chrome.com/docs/lighthouse/performance/performance-scoring
+- https://googlechrome.github.io/lighthouse-ci/docs/configuration.html
+- https://gtmetrix.com/blog/everything-you-need-to-know-about-the-new-gtmetrix-report-powered-by-lighthouse/
+- https://documentation.solarwinds.com/en/success_center/pingdom/content/topics/page-speed-check.htm
+
+Revalidate versions/features before adoption; provider grades do not share one scale.