@zaip-ai/cli 0.1.0 → 1.0.1

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-lib.mjs

@@ -0,0 +1,361 @@
+import { createReadStream } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+
+export async function filesUnder(root, suffix) {
+  const output = [];
+  async function visit(path) {
+    let entries;
+    try {
+      entries = await readdir(path, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) await visit(child);
+      else if (entry.isFile() && entry.name.endsWith(suffix)) output.push(child);
+    }
+  }
+  await visit(root);
+  return output.sort();
+}
+
+export function jsonLines(text) {
+  return text
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        const parsed = JSON.parse(line);
+        if (
+          !Array.isArray(parsed) &&
+          parsed &&
+          parsed.type === undefined &&
+          Object.keys(parsed).every((key) => /^\d+$|^sequence$/.test(key))
+        ) {
+          const numeric = Object.keys(parsed)
+            .filter((key) => /^\d+$/.test(key))
+            .map(Number);
+          return [[...Array(Math.max(...numeric) + 1)].map((_, index) => parsed[index])];
+        }
+        return [parsed];
+      } catch {
+        return [];
+      }
+    });
+}
+
+export function recordType(record) {
+  if (!Array.isArray(record)) return record.type;
+  return record[1] === "u"
+    ? "usage.recorded"
+    : record[1] === "f"
+      ? "run.finished"
+      : record[1] === "s"
+        ? "run.started"
+        : null;
+}
+
+export function recordSequence(record) {
+  return Array.isArray(record) ? record[3] : record.sequence;
+}
+
+export function recordOccurredAt(record) {
+  return Array.isArray(record) ? record[4] : record.occurred_at;
+}
+
+export function usageView(record) {
+  if (recordType(record) !== "usage.recorded") return null;
+  if (!Array.isArray(record)) return record;
+  const tokens = record[8] ?? [];
+  const cost = record[9] ?? [];
+  return {
+    event_id: record[2],
+    occurred_at: record[4],
+    phase: record[5],
+    classification_source: record[7],
+    tokens: {
+      input: tokens[0] ?? null,
+      cached_input: tokens[1] ?? null,
+      output: tokens[2] ?? null,
+      reasoning: tokens[3] ?? null,
+      total: tokens[4] ?? null,
+      source: tokens[5] ?? "unavailable",
+    },
+    source_segment_key: record[12] ?? null,
+    supersedes_event_id: record[13] ?? null,
+    activity_kind: record[6] ?? null,
+    cost: { usd: cost[0] ?? null, brl: cost[1] ?? null },
+    provider: record[10] ?? null,
+    model: record[11] ?? null,
+    source_occurred_at: record[14] ?? null,
+    context_stats: Array.isArray(record[15])
+      ? {
+          initial_pack_tokens: record[15][0],
+          tool_output_tokens: record[15][1],
+          files_opened: record[15][2],
+          snippets_opened: record[15][3],
+        }
+      : undefined,
+    runtime: Array.isArray(record[16])
+      ? { reasoning_effort: record[16][0], service_tier: record[16][1] }
+      : undefined,
+  };
+}
+
+export function withSequence(record, sequence) {
+  if (!Array.isArray(record)) return { ...record, sequence };
+  const copy = [...record];
+  copy[3] = sequence;
+  return copy;
+}
+
+function canonicalSegmentKey(sourceSegmentKey) {
+  const marker = sourceSegmentKey.lastIndexOf("@RUN-");
+  const withoutRun = marker < 0 ? sourceSegmentKey : sourceSegmentKey.slice(0, marker);
+  const normalized = withoutRun.replaceAll("\\", "/");
+  const sessionsMarker = normalized.toLowerCase().lastIndexOf("/sessions/");
+  return (sessionsMarker < 0 ? normalized : normalized.slice(sessionsMarker + 1)).toLowerCase();
+}
+
+export function usageStatus(usage) {
+  const superseded = new Set(usage.map((event) => event.supersedes_event_id).filter(Boolean));
+  const effective = usage.filter((event) => !superseded.has(event.event_id));
+  return {
+    effective,
+    measured: effective.some(
+      (event) => event.tokens?.input !== null && event.tokens?.output !== null,
+    ),
+    deduplicated: effective.some(
+      (event) => event.activity_kind === "duplicate_segment_reconciliation",
+    ),
+  };
+}
+
+export function duplicateUsageAssignments(runs) {
+  const groups = new Map();
+  for (const run of runs) {
+    for (const usage of usageStatus(run.usage).effective) {
+      if (
+        !usage.source_segment_key ||
+        usage.tokens?.input === null ||
+        usage.tokens?.output === null
+      ) {
+        continue;
+      }
+      const baseSegmentKey = canonicalSegmentKey(usage.source_segment_key);
+      const signature = JSON.stringify([
+        baseSegmentKey,
+        run.started.client_turn_id ?? null,
+        usage.tokens.input,
+        usage.tokens.cached_input,
+        usage.tokens.output,
+        usage.tokens.reasoning,
+        usage.tokens.total,
+      ]);
+      groups.set(signature, [
+        ...(groups.get(signature) ?? []),
+        { run, usage, base_segment_key: baseSegmentKey },
+      ]);
+    }
+  }
+  return [...groups.values()]
+    .filter((group) => new Set(group.map(({ run }) => run.started.run_id)).size > 1)
+    .map((group) =>
+      [...group].sort(
+        (left, right) =>
+          String(left.run.started.occurred_at).localeCompare(
+            String(right.run.started.occurred_at),
+          ) || left.run.started.run_id.localeCompare(right.run.started.run_id),
+      ),
+    );
+}
+
+export function exactCompletedSegment(started, segments) {
+  if (!started?.client_turn_id) return { segment: null, ambiguous: false };
+  const runStartedAt = Date.parse(started.occurred_at ?? "");
+  const matches = segments.filter((segment) => {
+    if (segment.turn_id !== started.client_turn_id || !segment.finished_at) return false;
+    const segmentFinishedAt = Date.parse(segment.finished_at);
+    return (
+      Number.isFinite(runStartedAt) &&
+      Number.isFinite(segmentFinishedAt) &&
+      segmentFinishedAt >= runStartedAt
+    );
+  });
+  return {
+    segment: matches.length === 1 ? matches[0] : null,
+    ambiguous: matches.length > 1,
+  };
+}
+
+function normalized(path) {
+  return resolve(path).replaceAll("\\", "/").toLowerCase();
+}
+
+export async function loadSegments(workspace) {
+  const sessionFiles = await filesUnder(join(homedir(), ".codex", "sessions"), ".jsonl");
+  const segments = [];
+  for (const file of sessionFiles) {
+    let workspaceMatches = false;
+    let sessionId = null;
+    let current = null;
+    let index = 0;
+    let model = null;
+    let effort = null;
+    let serviceTier = null;
+    const lines = createInterface({
+      input: createReadStream(file, { encoding: "utf8" }),
+      crlfDelay: Infinity,
+    });
+    for await (const line of lines) {
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const payload = record?.payload && typeof record.payload === "object" ? record.payload : null;
+      if (record.type === "session_meta" && typeof payload?.cwd === "string") {
+        workspaceMatches = normalized(payload.cwd) === normalized(workspace);
+        sessionId =
+          typeof payload.session_id === "string"
+            ? payload.session_id
+            : typeof payload.id === "string"
+              ? payload.id
+              : null;
+      }
+      if (!workspaceMatches) continue;
+      const settings = payload?.type === "thread_settings_applied" ? payload.thread_settings : null;
+      if (settings && typeof settings === "object") {
+        if (typeof settings.model === "string") {
+          model = settings.model;
+          if (current) current.model = model;
+        }
+        if (typeof settings.reasoning_effort === "string") {
+          effort = settings.reasoning_effort;
+          if (current) current.effort = effort;
+        }
+        if (typeof settings.service_tier === "string") {
+          serviceTier = settings.service_tier;
+          if (current) current.service_tier = serviceTier;
+        }
+      }
+      if (record.type === "turn_context" && typeof payload?.model === "string") {
+        model = payload.model;
+        if (current) current.model = model;
+      }
+      if (payload?.type === "task_started") {
+        index += 1;
+        current = {
+          key: `${normalized(file)}#${index}`,
+          file,
+          session_id: sessionId,
+          turn_id: typeof payload.turn_id === "string" ? payload.turn_id : null,
+          started_at: record.timestamp ?? null,
+          finished_at: null,
+          model,
+          effort,
+          service_tier: serviceTier,
+          usage: [],
+          raw: [],
+        };
+      }
+      if (!current) continue;
+      if (line.includes("RUN-") || line.includes("TASK-")) current.raw.push(line);
+      if (payload?.type === "token_count") {
+        const usage = payload?.info?.last_token_usage;
+        if (usage && typeof usage === "object")
+          current.usage.push({ ...usage, source_timestamp: record.timestamp ?? null });
+      }
+      if (payload?.type === "task_complete") {
+        current.finished_at = record.timestamp ?? null;
+        if (current.usage.length) segments.push(current);
+        current = null;
+      }
+    }
+    if (current?.usage.length) segments.push(current);
+  }
+  return segments.map((segment) => ({ ...segment, raw: segment.raw.join("\n") }));
+}
+
+export function aggregate(segment) {
+  const result = { input: 0, cached_input: 0, output: 0, reasoning: 0, total: 0 };
+  for (const usage of segment.usage) {
+    const input = Number.isFinite(usage.input_tokens) ? usage.input_tokens : 0;
+    const output = Number.isFinite(usage.output_tokens) ? usage.output_tokens : 0;
+    result.input += input;
+    result.cached_input += Number.isFinite(usage.cached_input_tokens)
+      ? usage.cached_input_tokens
+      : 0;
+    result.output += output;
+    result.reasoning += Number.isFinite(usage.reasoning_output_tokens)
+      ? usage.reasoning_output_tokens
+      : 0;
+    result.total += input + output;
+  }
+  return result;
+}
+
+export async function pricingFor(workspace, model, tokens) {
+  let catalog;
+  try {
+    catalog = JSON.parse(
+      await readFile(join(workspace, ".zaip-aios", "pricing", "models.json"), "utf8"),
+    );
+  } catch {
+    return { usd: null, brl: null };
+  }
+  const lower = String(model ?? "").toLowerCase();
+  const matchesIdentity = (identity) => {
+    const normalizedIdentity = identity.toLowerCase();
+    if (lower === normalizedIdentity) return true;
+    const suffix = lower.slice(normalizedIdentity.length);
+    return (
+      suffix.startsWith("@") ||
+      suffix.startsWith(":") ||
+      suffix.startsWith("/") ||
+      /^-\d{4}-\d{2}-\d{2}(?:$|[.:@/])/.test(suffix)
+    );
+  };
+  const price =
+    catalog.models?.find(
+      (item) => matchesIdentity(item.id) || item.aliases?.some(matchesIdentity),
+    ) ?? null;
+  if (!price) return { usd: null, brl: null };
+  const uncached = Math.max(0, tokens.input - tokens.cached_input);
+  const reasoning = Math.max(0, tokens.reasoning ?? 0);
+  const visibleOutput = Math.max(0, tokens.output - reasoning);
+  const longContext =
+    price.long_context_threshold_tokens !== null &&
+    price.long_context_threshold_tokens !== undefined &&
+    tokens.input > price.long_context_threshold_tokens;
+  const inputMultiplier = longContext ? (price.long_context_input_multiplier ?? 1) : 1;
+  const outputMultiplier = longContext ? (price.long_context_output_multiplier ?? 1) : 1;
+  const usd =
+    (uncached * price.input_per_million_usd * inputMultiplier +
+      tokens.cached_input * (price.cached_input_per_million_usd ?? 0) * inputMultiplier +
+      visibleOutput * price.output_per_million_usd * outputMultiplier +
+      reasoning *
+        (price.reasoning_per_million_usd ?? price.output_per_million_usd) *
+        outputMultiplier) /
+    1_000_000;
+  const fxFiles = await filesUnder(join(workspace, ".zaip-aios", "pricing", "fx"), ".json");
+  let rate = null;
+  if (fxFiles.length) {
+    try {
+      rate = JSON.parse(await readFile(fxFiles.at(-1), "utf8")).rate ?? null;
+    } catch {}
+  }
+  return { usd, brl: rate === null ? null : usd * rate };
+}
+
+export function sameCost(left, right) {
+  const close = (a, b) =>
+    (a === null && b === null) ||
+    (typeof a === "number" && typeof b === "number" && Math.abs(a - b) < 0.0000005);
+  return close(left?.usd ?? null, right.usd) && close(left?.brl ?? null, right.brl);
+}

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-lib.test.mjs

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import {
+  aggregate,
+  duplicateUsageAssignments,
+  exactCompletedSegment,
+  jsonLines,
+  pricingFor,
+  recordSequence,
+  recordType,
+  usageStatus,
+  usageView,
+  withSequence,
+} from "./reconcile-telemetry-lib.mjs";
+
+const roots = [];
+after(async () => Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))));
+
+test("normalizes compact and object Run records without changing usage totals", () => {
+  const compact = [
+    2,
+    "u",
+    "RUN-1:usage",
+    2,
+    "2026-07-15T22:00:00.000Z",
+    "execution",
+    "test",
+    "current_context",
+    [10, 4, 3, 1, 13, "provider_reported"],
+    [0.1, 0.5],
+  ];
+  const records = jsonLines(
+    `${JSON.stringify({ type: "run.started", sequence: 1 })}\n${JSON.stringify(compact)}\n`,
+  );
+  assert.equal(recordType(records[0]), "run.started");
+  assert.equal(recordType(records[1]), "usage.recorded");
+  assert.equal(recordSequence(records[1]), 2);
+  assert.deepEqual(usageView(records[1]).tokens, {
+    input: 10,
+    cached_input: 4,
+    output: 3,
+    reasoning: 1,
+    total: 13,
+    source: "provider_reported",
+  });
+  assert.equal(recordSequence(withSequence(records[1], 7)), 7);
+  assert.deepEqual(
+    aggregate({
+      usage: [
+        { input_tokens: 10, cached_input_tokens: 4, output_tokens: 3, reasoning_output_tokens: 1 },
+      ],
+    }),
+    {
+      input: 10,
+      cached_input: 4,
+      output: 3,
+      reasoning: 1,
+      total: 13,
+    },
+  );
+});
+
+test("prices only exact or governed model identities", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-reconcile-lib-"));
+  roots.push(root);
+  await mkdir(join(root, ".zaip-aios", "pricing"), { recursive: true });
+  await writeFile(
+    join(root, ".zaip-aios", "pricing", "models.json"),
+    JSON.stringify({
+      models: [
+        {
+          id: "gpt-test",
+          aliases: ["gpt-test-alias"],
+          input_per_million_usd: 10,
+          cached_input_per_million_usd: 1,
+          output_per_million_usd: 20,
+          reasoning_per_million_usd: 30,
+          long_context_threshold_tokens: null,
+        },
+      ],
+    }),
+  );
+  const tokens = { input: 100, cached_input: 40, output: 20, reasoning: 5 };
+  const expected = (60 * 10 + 40 * 1 + 15 * 20 + 5 * 30) / 1_000_000;
+  assert.equal((await pricingFor(root, "gpt-test", tokens)).usd, expected);
+  assert.equal((await pricingFor(root, "unknown", tokens)).usd, null);
+});
+
+test("selects only one completed local segment for an exact Run turn", () => {
+  const started = {
+    client_turn_id: "turn-1",
+    occurred_at: "2026-07-17T12:00:00.000Z",
+  };
+  const completed = {
+    key: "session#1",
+    turn_id: "turn-1",
+    finished_at: "2026-07-17T12:03:00.000Z",
+  };
+  assert.deepEqual(exactCompletedSegment(started, [completed]), {
+    segment: completed,
+    ambiguous: false,
+  });
+  assert.deepEqual(exactCompletedSegment(started, [{ ...completed, finished_at: null }]), {
+    segment: null,
+    ambiguous: false,
+  });
+  assert.deepEqual(
+    exactCompletedSegment(started, [completed, { ...completed, key: "session#2" }]),
+    {
+      segment: null,
+      ambiguous: true,
+    },
+  );
+});
+
+test("detects only exact duplicate segment assignments across Runs", () => {
+  const usage = (
+    runId,
+    total,
+    output = 10,
+    sourcePrefix = "",
+    sourceOccurredAt = "2026-07-17T12:03:00.000Z",
+  ) => ({
+    event_id: `${runId}:usage`,
+    source_segment_key: `${sourcePrefix}sessions/2026/07/17/session.jsonl#1@${runId}`,
+    source_occurred_at: sourceOccurredAt,
+    supersedes_event_id: null,
+    tokens: {
+      input: total - output,
+      cached_input: total - output - 5,
+      output,
+      reasoning: 2,
+      total,
+    },
+  });
+  const run = (runId, occurredAt, total, output, sourcePrefix, sourceOccurredAt) => ({
+    started: {
+      run_id: runId,
+      client_turn_id: "turn-1",
+      occurred_at: occurredAt,
+    },
+    usage: [usage(runId, total, output, sourcePrefix, sourceOccurredAt)],
+  });
+  const first = run("RUN-FIRST", "2026-07-17T12:00:00.000Z", 100);
+  const duplicate = run(
+    "RUN-DUPLICATE",
+    "2026-07-17T12:01:00.000Z",
+    100,
+    undefined,
+    "C:/Users/david/.codex/",
+    "2026-07-17T12:04:00.000Z",
+  );
+  const legitimateDelta = run("RUN-DELTA", "2026-07-17T12:02:00.000Z", 20, 5);
+
+  const groups = duplicateUsageAssignments([duplicate, legitimateDelta, first]);
+
+  assert.equal(groups.length, 1);
+  assert.deepEqual(
+    groups[0].map(({ run: item }) => item.started.run_id),
+    ["RUN-FIRST", "RUN-DUPLICATE"],
+  );
+  assert.equal(groups[0][0].base_segment_key, "sessions/2026/07/17/session.jsonl#1");
+});
+
+test("keeps duplicate reconciliation unavailable and protected from backfill", () => {
+  const original = {
+    event_id: "RUN-DUPLICATE:usage",
+    supersedes_event_id: null,
+    activity_kind: "implementation",
+    tokens: { input: 90, output: 10 },
+  };
+  const correction = {
+    event_id: "RUN-DUPLICATE:deduplicate:000001",
+    supersedes_event_id: original.event_id,
+    activity_kind: "duplicate_segment_reconciliation",
+    tokens: { input: null, output: null },
+  };
+
+  const status = usageStatus([original, correction]);
+
+  assert.equal(status.measured, false);
+  assert.equal(status.deduplicated, true);
+  assert.deepEqual(status.effective, [correction]);
+});

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

@@ -1,12 +1,16 @@
 ---
 name: zaip-skill-requirements
-description: Create, inspect, validate, version, and apply ZAIP Requirements and deterministic Acceptance Criteria grouped by system area.
+description: Create, version, validate, and promote ZAIP Requirements and Acceptance Criteria.
 ---
 
 # Manter Requirements
 
-1. Mantenha Requirements pequenos e identificados no arquivo estável da área em `.agents/requirements/<area>.md`.
-2. Escreva Acceptance Criteria observáveis, determinísticos e identificados; evite termos vagos como “adequado”.
-3. Faça PRD, SPEC, Change, Task, teste e evidência referenciar IDs, sem duplicar a fonte de verdade.
-4. Durante implementação, registre o delta proposto na Change; não altere a verdade ativa antes das evidências passarem.
-5. Ao concluir, aplique o delta de forma versionada e verifique Requirements órfãos, AC sem evidência e referências quebradas.
+1. Agrupe Requirements por área estável em `.agents/requirements/<area>.md`; não crie arquivo por Task, mês ou Change.
+2. Use IDs únicos e AC observável/determinístico com método de verificação explícito; rejeite “adequado”, “rápido” ou “funciona” sem limiar.
+3. Faça PRD, SPEC, Change, Task, teste e evidência referenciar IDs sem duplicar a verdade.
+4. Durante planejamento/execução, registre o delta como `proposed` na Change; não reescreva regra ativa antecipadamente.
+5. Para promover a `active`, exija todos os ACs cobertos por evidência, testes/evals terminais, referências válidas e ausência de regressão conhecida.
+6. Registre versão/proveniência; depreque com substituto explícito quando aplicável, sem apagar histórico ainda referenciado.
+7. Valide órfãos, duplicatas, AC sem evidência, aliases e referências quebradas antes de concluir.
+8. Diferencie assurance de Task e de entrega: `lite` usa exatamente 1 validação/1 Evidence, `standard` 2 ou 3, `critical` 3+ com controles independentes; SPEC/PRD adicionam pelo menos 3 validações/3 Evidences parentais, matriz completa e integração real.
+9. Não promova Requirement com evidência de candidato antigo, sem commit/hash quando exigido ou com alegação de ambiente superior ao realmente validado.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP Requirements"
-  short_description: "Maintain verifiable requirements and ACs"
-  default_prompt: "Use $zaip-skill-requirements to create or validate traceable Requirements and Acceptance Criteria."
+  short_description: "Maintain deterministic Requirements and Acceptance Criteria."
+  default_prompt: "Use $zaip-skill-requirements to create, validate, or promote traceable Requirements and Acceptance Criteria."

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

@@ -0,0 +1,18 @@
+---
+name: zaip-skill-review
+description: Review ZAIP work read-only against Requirements, diff, tests, evidence, and results.
+---
+
+# Revisar sem alterar
+
+Esta skill é read-only. Um pedido de revisão não autoriza corrigir, concluir estados nem publicar.
+
+1. Resolva a cadeia PRD/SPEC/Task → Change → Execution/Runs e carregue só Requirements, Rules, diff, testes e evidências relacionados.
+2. Para cada AC, classifique separadamente `implemented`, `evidenced` e `validated_in_production` como `yes`, `no`, `unknown` ou `not_applicable` justificado.
+3. Verifique escopo, regressões, arquitetura, segurança, tratamento de falhas, observabilidade e consistência das decisões.
+4. Não trate teste declarado como teste executado; não trate execução local como validação em produção.
+5. Entregue findings priorizados com arquivo/linha quando possível, impacto, evidência e ação recomendada.
+6. Se não houver findings, declare riscos residuais e lacunas de evidência.
+7. Correções aprovadas exigem autorização separada e começam uma nova Task. Inicie seu Run com `--work-type rework`, relacione somente IDs já conhecidos e deixe ancestral desconhecido como `null`; nunca leia todo o histórico para adivinhar vínculos. A revisão original permanece imutável.
+8. Valide o perfil quantitativo e semântico: `lite` exatamente 1/1, `standard` exatamente 2/2 ou 3/3, `critical` 3+ e SPEC/PRD com 3+ artefatos parentais, matriz, integração, review independente e commit final.
+9. Para cleanroom, ambiente representativo ou produção, confira hash do candidato, identidade do ambiente, reviewer independente e Run observado; teste local não promove esses estados.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Review"
+  short_description: "Review changes against evidence and acceptance criteria."
+  default_prompt: "Use $zaip-skill-review to perform a read-only review from Requirements and diff through evidence and results."

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

@@ -0,0 +1,19 @@
+---
+name: zaip-skill-rules
+description: Create and validate project ZAIP Rules while preserving core Rules.
+---
+
+# Manter Rules do projeto
+
+1. Confirme que a instrução é durável e repetível; preferência temporária deve ficar no trabalho ativo, não virar Rule.
+2. Procure por IDs e temas equivalentes em `.agents/rules/project` e nas Rules ZAIP aplicáveis antes de criar outra.
+3. Crie ou refine somente `.agents/rules/project/<nome>.md` com ID `RULE-*` único; `load` em `always`, `auto`, `file_match` ou `manual`; `priority` em `critical`, `high`, `medium` ou `low`; `max_context_tokens` positivo; `requires` com IDs existentes. Exija `globs` não vazios quando `load: file_match`.
+4. Escreva regras pequenas, imperativas e verificáveis; mova explicações extensas para Requirements ou documentação.
+5. Detecte contradições, ciclos de `requires`, duplicação de IDs e budgets excessivos.
+6. Rode `zaip doctor` e `zaip context validate --query "<cenário da Rule>"`; quando a orientação publicada mudar, rode `zaip adapters build` e `zaip adapters check`.
+
+## Ownership
+
+- `.agents/rules/zaip` é fornecida pelo framework e só muda numa evolução/upgrade explícito do ZAIP.
+- `.agents/rules/project` é específica do repositório, preservada por upgrade e nunca entra no release público.
+- Não crie versões mensais ou uma Rule por Change. Edite a Rule fixa somente quando a regra real mudar; o histórico fica no Git e na Change.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Project Rules"
+  short_description: "Create and validate project-owned ZAIP Rules."
+  default_prompt: "Use $zaip-skill-rules to create or refine project-specific Rules without editing ZAIP core Rules."

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

@@ -0,0 +1,30 @@
+---
+name: zaip-skill-security
+description: Assess ZAIP security read-only, compare or verify the zaip-aios-security and zaip-aios-full-access permission profiles, or verify controls during authorized delivery.
+---
+
+# Avaliar e verificar segurança
+
+1. Escolha o modo antes de agir:
+   - `assess`: somente leitura; reporte findings provisórios sem editar arquivos, persistir evidência ou mudar estado.
+   - `verify`: use apenas dentro de uma execução já autorizada; rode checks e persista evidência sanitizada na Change/Execution materializada.
+2. Classifique risco e superfície: dados, autenticação/autorização, tenants, rede, filesystem, dependências, CI e supply chain.
+3. Procure segredos e PII sem imprimir valores; masque evidências e nunca persista credenciais em `.agents`.
+4. Verifique menor privilégio, boundary de confiança, validação de entrada, autorização por recurso e isolamento de tenant.
+5. Revise dependências/lockfile, scripts de instalação, artefatos gerados e fontes externas não confiáveis.
+6. Para leitura de dados, imponha filtro, limite, tenant e redaction; diferencie resultado vazio de falta de acesso, RLS ou erro.
+7. Em risco `critical`, exija threat model, rollout, rollback e gates antes de executar.
+8. Mapeie cada finding ou teste a Requirement/AC. No modo `assess`, apenas proponha o vínculo; no `verify`, registre-o sem inventar resultado.
+9. Nunca reduza um controle ou execute replay/recuperação sem autorização explícita e validação de idempotência.
+
+## Perfis de permissão Codex
+
+- Leia `.agents/zaip-aios/guides/10-seguranca.md` ao avaliar, selecionar ou alterar um perfil.
+- Prefira `zaip-aios-security`: use uma tabela da raiz física absoluta do repositório, com `"."`, `.git`, `.agents` e `.codex` como `write`; permita escrita em `~/.ssh` somente para fluxos Git/SSH explicitamente autorizados e limite a rede de comandos a `github.com` com `mode = "limited"`. Não use `extends = ":workspace"` nem `:workspace_roots` para esse perfil no Windows, pois o Codex protege `.agents` e `.codex` nesses modos.
+- Use `approval_policy = "never"`; a autorização de deploy continua sendo exigida pelas Rules, hooks e skills, e a rede nativa do perfil permanece limitada a `github.com`.
+- Trate `zaip-aios-full-access` como exceção de maior risco: ele permite escrita nativa em `C:\` inteiro e rede completa, sujeitas às ACLs e privilégios do Windows.
+- Ao autorizar full access, registre a necessidade e verifique as camadas compensatórias: pedido explícito, escopo do `AGENTS.md`, Rules/skills, hook `PreToolUse`, regras `forbidden`, política GitHub, proteção de segredos, lifecycle sanitizado, subagentes de menor privilégio e controles do sistema operacional.
+- Nunca descreva essas camadas como equivalentes ao isolamento nativo. Elas reduzem risco, mas somente `zaip-aios-security` nega tecnicamente escrita fora do workspace e restringe a rede de comandos ao GitHub.
+- Recomende retornar ao perfil restrito assim que a operação excepcional terminar.
+
+Falha de segurança terminal bloqueia conclusão; incerteza relevante deve ficar explícita, não ser tratada como aprovação.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Security"
+  short_description: "Assess profiles and ZAIP security controls."
+  default_prompt: "Use $zaip-skill-security to compare ZAIP permission profiles or verify security controls during authorized work."