@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/skills/zaip-skill-executar-fila-pronta/SKILL.md

@@ -9,10 +9,12 @@ Use esta skill para uma rodada idempotente que reivindica e executa **um único
 
 1. A primeira ação da conversa agendada chama `codex_app set_thread_title` sem `threadId`, usando a hora local `America/Sao_Paulo` no formato exato `[YYYY-MM-DD-T-HH-mm] Tarefa Agendada`. Registre a falha de renomeação observada e continue para a fila; ela não bloqueia a rodada.
 2. Valide o checkout local, `zaip.enabled: true`, registros canônicos e runtime. Leia `.agents/dashboard/work-priority.json` quando existir; ausência ou conteúdo inválido equivale a nenhuma prioridade manual, nunca a uma ordem inventada.
-3. Antes de selecionar, chame `node .agents/skills/zaip-skill-executar-fila-pronta/scripts/ready-queue-lease.mjs acquire` na raiz do projeto. Ele cria atomicamente `.local/automation/ready-queue.lock.json` (diretório local não versionado) com `owner_token` aleatório, `fencing_token`, `acquired_at` e `expires_at`. Guarde o `owner_token` e `fencing_token` retornados; não os invente. O `fencing_token` é um inteiro monotônico: toda aquisição que substitui um lock expirado recebe valor maior que o último valor observado. Se existir lock válido de outra rodada, retorne sem efeito; nunca force a sobreposição. Renove o mesmo lock com `ready-queue-lease.mjs renew OWNER FENCE` antes de reivindicar o item selecionado e nos checkpoints de uma execução longa. Antes de cada efeito (incluindo iniciar uma Execution), chame `ready-queue-lease.mjs assert OWNER FENCE` e exija sucesso; se falhar, encerre a rodada sem executar mais efeitos. Libere com `ready-queue-lease.mjs release OWNER FENCE` somente ao terminar e apenas se o `owner_token` ainda corresponder; locks expirados podem ser substituídos atomicamente.
+3. Antes de selecionar, chame `node .agents/skills/zaip-skill-executar-fila-pronta/scripts/ready-queue-lease.mjs acquire` na raiz do projeto. Ele cria atomicamente `.agents/private/state/automation/ready-queue.lock.json` (diretório local não versionado) com `owner_token` aleatório, `fencing_token`, `acquired_at` e `expires_at`. Guarde o `owner_token` e `fencing_token` retornados; não os invente. O `fencing_token` é um inteiro monotônico: toda aquisição que substitui um lock expirado recebe valor maior que o último valor observado. Se existir lock válido de outra rodada, retorne sem efeito; nunca force a sobreposição. Renove o mesmo lock com `ready-queue-lease.mjs renew OWNER FENCE` antes de reivindicar o item selecionado e nos checkpoints de uma execução longa. Antes de cada efeito (incluindo iniciar uma Execution), chame `ready-queue-lease.mjs assert OWNER FENCE` e exija sucesso; se falhar, encerre a rodada sem executar mais efeitos. Libere com `ready-queue-lease.mjs release OWNER FENCE` somente ao terminar e apenas se o `owner_token` ainda corresponder; locks expirados podem ser substituídos atomicamente.
 4. Consulte `zaip task ready-next --json` para a seleção canônica e determinística: PRD `ready`; depois SPEC `ready` independente; depois Task-first standalone `prepared`/`planned`, com dependências concluídas e exatamente um PreparedPlan resolvível: `prepared_plan` inline válido **ou** `plan_ref` válido, nunca ambos. A Task ainda não pode ter Execution vinculada e nunca pode ter sido iniciada ou tentada. O comando exclui Task sem `status: planned`, com `started_at`, `attempt_count` diferente de zero, Execution existente, estado de plano ambíguo, ou cujo próprio ID apareça em `task next` ou no conjunto materializado concorrente. Exclui também descendentes de PRD/SPEC e itens `active`, `blocked`, `failed`, `cancelled` ou terminais. Falha de leitura/validação não é fila vazia: bloqueie a rodada.
 5. O seletor usa `.agents/dashboard/work-priority.json`: itens enumerados no Kanban vêm primeiro e mantêm a ordem de cima para baixo; os sem enumeração entram depois por `created_at` e ID. Um arquivo inválido equivale a nenhuma prioridade manual. Considere PRDs antes de SPECs, e SPECs antes de Tasks. Releia `zaip task ready-next --json` sob o lease e reivindique **somente o primeiro item superior elegível** com `ready-queue-lease.mjs claim OWNER FENCE ITEM_ID`. Uma segunda reivindicação de outro ID com o mesmo lease é rejeitada pelo código; não transforme os demais candidatos em execução nesta rodada. Depois do claim, repita `zaip task ready-next --json`: se o item mudou ou ficou inelegível, registre a disputa e não escolha outro.
 6. Execute somente o item reivindicado, pelo comando explícito no menor grão (`prd execute`, `spec execute` ou `task execute`). Para uma Task-first elegível, use `task execute` para materializar sua Execution; não crie a Execution por outro atalho. Se o item deixar de ser elegível antes do início, registre a disputa e termine a rodada sem selecionar o próximo. Preserve os gates de write scope, dependências, evidências, testes e finalizador; uma seleção não é autorização para ignorar qualquer gate.
 7. Registre o resultado do único item, a ausência de candidatos ou a disputa observada, e solte o lease. Sem candidato, retorne `no_eligible_work`; com precondição ausente, conflito de lease ou estado ambíguo, falhe fechado e não altere registros.
 
+Na primeira aquisição após a migração oficial, o contador anterior é lido do arquivo legado preservado e incrementado no estado privado. O arquivo histórico não é reescrito. Se a migração ainda não terminou ou o contador arquivado estiver ausente ou inválido, a fila recusa a aquisição; nunca apague o estado para reiniciar o contador.
+
 Esta skill não cria um agendamento. Ela só pode ser chamada pela automação nativa do Codex Desktop ou por um usuário com autoridade explícita para executar o trabalho selecionado.

package/templates/.agents/skills/zaip-skill-executar-fila-pronta/scripts/ready-queue-fence.mjs

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
+import { readArchivedReadyQueueLease } from "./ready-queue-storage.mjs";
 
 export async function acquireReadyQueueFence(lockPath, input) {
   return withMutex(lockPath, async () => {
@@ -85,7 +86,7 @@ async function readLease(lockPath) {
   try {
     return JSON.parse(await readFile(lockPath, "utf8"));
   } catch (error) {
-    if (error?.code === "ENOENT") return null;
+    if (error?.code === "ENOENT") return readArchivedReadyQueueLease(lockPath);
     throw error;
   }
 }

package/templates/.agents/skills/zaip-skill-executar-fila-pronta/scripts/ready-queue-lease.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { directory } from "../../zaip-skill-worktree-recovery/scripts/durable-state-files.mjs";
 import {
   acquireReadyQueueFence,
   assertReadyQueueFence,
@@ -10,7 +11,7 @@ import {
 } from "./ready-queue-fence.mjs";
 
 const root = process.cwd();
-const lockPath = resolve(root, ".local/automation/ready-queue.lock.json");
+const lockPath = resolve(root, ".agents/private/state/automation/ready-queue.lock.json");
 const [action, ...args] = process.argv.slice(2);
 const now = new Date().toISOString();
 const expiry = new Date(Date.now() + 4 * 60 * 60 * 1000).toISOString();
@@ -20,6 +21,7 @@ try {
   if (!/^zaip:\s*\r?\n\s+enabled: true\s*$/m.test(config)) {
     throw new Error("ZAIP must be enabled in this checkout");
   }
+  await directory(root, ".agents/private/state/automation");
   let result;
   if (action === "acquire" && args.length === 0) {
     result = await acquireReadyQueueFence(lockPath, {

package/templates/.agents/skills/zaip-skill-executar-fila-pronta/scripts/ready-queue-storage.mjs

@@ -0,0 +1,40 @@
+import assert from "node:assert/strict";
+import { lstat, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { resolveHistoricalLocalArchive } from "../../../tools/historical-local-archive.mjs";
+
+/** Seed only the canonical queue from its preserved archive; never create a second legacy writer. */
+export async function readArchivedReadyQueueLease(lockPath) {
+  const root = resolve(dirname(lockPath), "../../../..");
+  if (resolve(root, ".agents/private/state/automation/ready-queue.lock.json") !== lockPath)
+    return null;
+  const originalDirectory = resolve(root, ".local/automation");
+  const exists = await lstat(originalDirectory).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  assert(!exists, "Complete the authenticated storage migration before using the ready queue");
+  const archived = await resolveHistoricalLocalArchive(root, ".local/automation");
+  if (archived === originalDirectory) return null;
+  const source = await resolveHistoricalLocalArchive(
+    root,
+    ".local/automation/ready-queue.lock.json",
+  );
+  assert(
+    source !== resolve(root, ".local/automation/ready-queue.lock.json"),
+    "Archived queue fence is missing; refusing to reset it",
+  );
+  const info = await lstat(source);
+  assert(info.isFile() && info.size <= 16384);
+  const value = JSON.parse(await readFile(source, "utf8"));
+  assert(
+    typeof value.owner_token === "string" &&
+      value.owner_token.length > 0 &&
+      value.owner_token.length <= 256,
+  );
+  assert(Number.isSafeInteger(value.fencing_token) && value.fencing_token > 0);
+  assert(
+    Number.isFinite(Date.parse(value.acquired_at)) && Number.isFinite(Date.parse(value.expires_at)),
+  );
+  return value;
+}

package/templates/.agents/skills/zaip-skill-executar-fila-pronta/scripts/ready-queue-storage.test.mjs

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { acquireReadyQueueFence, assertReadyQueueFence } from "./ready-queue-fence.mjs";
+import { readArchivedReadyQueueLease } from "./ready-queue-storage.mjs";
+
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+async function fixture(t) {
+  const root = await realpath(await mkdtemp(join(tmpdir(), "zaip-ready-storage-")));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const put = async (name, value) => {
+    await mkdir(dirname(join(root, name)), { recursive: true });
+    await writeFile(join(root, name), value);
+  };
+  const destination = ".agents/private/state/local-legacy/directories/automation";
+  const original = JSON.stringify({
+    owner_token: "archived-owner",
+    fencing_token: 7,
+    acquired_at: "2026-01-01T00:00:00Z",
+    expires_at: "2026-01-01T01:00:00Z",
+  });
+  await put(`${destination}/ready-queue.lock.json`, original);
+  const identity = await stat(join(root, destination));
+  const body = {
+    schema_version: 1,
+    root,
+    rows: [
+      {
+        source: ".local/automation",
+        destination,
+        kind: "directory",
+        dev: identity.dev,
+        ino: identity.ino,
+        contents: "opaque-preserved-by-atomic-rename",
+      },
+    ],
+  };
+  const plan = { ...body, id: digest(JSON.stringify(body)) };
+  await put(".agents/private/state/local-legacy/index.json", JSON.stringify(plan));
+  await put(
+    ".agents/state/storage-migrations/local-archive.json",
+    JSON.stringify({ id: plan.id, manifest_sha256: digest(JSON.stringify(plan)) }),
+  );
+  return {
+    root,
+    put,
+    original,
+    destination,
+    lock: join(root, ".agents/private/state/automation/ready-queue.lock.json"),
+  };
+}
+test("archived queue keeps the monotonic fence after local deletion without rewriting history", async (t) => {
+  const f = await fixture(t);
+  const first = await acquireReadyQueueFence(f.lock, {
+    owner_token: "current-owner",
+    now: "2026-01-02T00:00:00Z",
+    expires_at: "2026-01-02T01:00:00Z",
+  });
+  assert.equal(first.fencing_token, 8);
+  await f.put(".local/temp/fixture.txt", "discardable");
+  await rm(join(f.root, ".local"), { recursive: true });
+  const next = await acquireReadyQueueFence(f.lock, {
+    owner_token: "next-owner",
+    now: "2026-01-03T00:00:00Z",
+    expires_at: "2026-01-03T01:00:00Z",
+  });
+  assert.equal(next.fencing_token, 9);
+  assert.equal(await assertReadyQueueFence(f.lock, first, "2026-01-03T00:01:00Z"), false);
+  assert.equal(
+    await readFile(join(f.root, f.destination, "ready-queue.lock.json"), "utf8"),
+    f.original,
+  );
+});
+test("legacy writer and incomplete archive cannot reset the queue fence", async (t) => {
+  const f = await fixture(t);
+  await f.put(".local/automation/ready-queue.lock.json", f.original);
+  await assert.rejects(
+    readArchivedReadyQueueLease(f.lock),
+    /Complete the authenticated storage migration/,
+  );
+  await rm(join(f.root, ".local"), { recursive: true });
+  await rm(join(f.root, f.destination, "ready-queue.lock.json"));
+  await assert.rejects(readArchivedReadyQueueLease(f.lock), /refusing to reset/);
+});

package/templates/.agents/skills/zaip-skill-executar-fila-pronta/scripts/scheduled-ready-queue-contract.test.mjs

@@ -52,7 +52,7 @@ test("hourly ready queue contracts the native Codex scheduler and one ordered it
   assert.match(executor, /descendentes de PRD\/SPEC/);
   assert.match(executor, /`active`, `blocked`, `failed`, `cancelled` ou terminais/);
   assert.match(executor, /\.agents\/dashboard\/work-priority\.json/);
-  assert.match(executor, /\.local\/automation\/ready-queue\.lock\.json/);
+  assert.match(executor, /\.agents\/private\/state\/automation\/ready-queue\.lock\.json/);
   assert.match(executor, /owner_token/);
   assert.match(executor, /fencing_token/);
   assert.match(executor, /inteiro monotônico/);

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

@@ -25,8 +25,16 @@ Antes de encerrar com trabalho pendente ou responder a uma falha, aplique [conti
 
 ## Passos de execução
 
+Antes de iniciar ou retomar entrega, aplique a política de uma versão por vez:
+o erro `release_version_conflict` preserva o ciclo e informa a versão atual e o
+próximo passo. Planejamento futuro pode permanecer draft. Captura incorreta de
+conversa sem alvo/filhos usa [promoção tipada no mesmo turno](references/conversation-promotion.md)
+com autoridade observada; não peça “continuar deploy” por mero conflito de modo.
+
 O intake de trabalho novo retorna `assurance_planning`: obrigações de prova por AC, revisão independente, mutação, rollback e candidato final. Essa saída não é aprovação. Defina cenário, expectativa, ambiente e responsável antes de editar; use ACs funcionais específicos, evitando depender somente de `AC-WORK-001-09`. Antes da qualificação/publicação, registre as provas já coletadas e execute `task assurance TASK --preflight --evidence EVD-ID[,EVD-ID] --json`. Corrija lacunas antes de iniciar a publicação; a prova da publicação e o Gui permanecem posteriores. Não repita testes válidos apenas para preencher artefatos: referencie a execução observada e revalide somente quando seu candidato, dependências, ambiente ou contrato tiverem mudado.
 
+Antes de invocar o último Gui, execute também `task verify TASK --evidence EVD-ID[,EVD-ID] --json`: o preflight de assurance valida somente artefatos, enquanto `task verify` inclui cobertura de lifecycle e Decision exigida. Esses comandos não substituem o candidato final nem aprovam publicação. Entregue ao Gui o inventário causal do candidato; não confunda `owned_changed_files: []` de um revisor somente leitura com ausência de alterações na entrega. O fechamento deriva o resultado da Task dos commits atribuídos, mantém a decisão original e ainda valida escopo, drift e evidências.
+
 1. Carregue o PreparedPlan e valide hash, origem, Requirements/AC, DAG, write scopes e estado atual. Antes de selecionar executor, carregue as Rules aplicáveis; para decisão comercial, use `$RULE-SPECIALIST-ROUTING` como fonte única da matriz de roteamento. Ao construir ou diagnosticar o plano externo, leia [o contrato compacto](references/prepared-plan.md).
 2. Materialize idempotentemente Change, Tasks e Execution antes da primeira alteração do produto.
 3. A partir da tentativa explícita de `execute`, classifique uso como `execution`; inicie Execution, Changes, Tasks elegíveis e Runs com atribuição ao nível de entrada (`task`, `spec` ou `prd`). Ausência de diff não retroage a fase: registre `changed_files` vazio e o resultado real.
@@ -35,7 +43,7 @@ O intake de trabalho novo retorna `assurance_planning`: obrigações de prova po
 6. Registre decisões humanas/IA, uso por fase, evidências por AC, testes, evals e arquivos alterados. Antes de implementar, consulte `zaip task assurance TASK --json`, aplique [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md) e [o fluxo de candidato e preparo](references/candidate-workflow.md). Falta de prova obrigatória impede aceite, não trabalho independente.
 7. Para toda Task com mutação, produza um commit canônico isolado antes de `completed`, com provider efetivo exclusivamente `CODEX` ou `CLAUDE` e sem `AUTO`. Linhagem evidenciada usa `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <título da Task>` com blocos disponíveis; Task sem PRD/SPEC usa `[CODEX|CLAUDE] [Task-first:XXXX] <título da Task>`. Limite o assunto a 96 caracteres sem cortar palavras, preserve IDs completos disponíveis nos trailers `ZAIP-PRD`, `ZAIP-SPEC`, `ZAIP-Task`, `ZAIP-Change`, `ZAIP-Execution` e `ZAIP-Agent`, e não combine Tasks no mesmo commit. Commits de produto, inclusive deploy particionado, exigem essa identidade; somente alterações em `.agents/records/` e `.local/` dispensam Task. Valide o índice e siga [o contrato portátil](../zaip-skill-task/references/commit-policy.md).
 8. Respeite a política do plano: use `zaip verify --changed --risk <risk>` no modo `scoped`; reserve `pnpm verify` para `full`, risco critical ou gate final exigido.
-9. Em cada `run usage`, leia `budget.context_refresh_required` e `budget.checkpoint_required`. O runtime grava o checkpoint sanitizado em `.local/checkpoints/`; quando sinalizado, reconstrua contexto somente de IDs ativos, diff e findings, descarte outputs brutos antigos e continue apenas com autoridade.
+9. Em cada `run usage`, leia `budget.context_refresh_required` e `budget.checkpoint_required`. O runtime grava o checkpoint sanitizado em `.agents/private/state/checkpoints/`; quando sinalizado, reconstrua contexto somente de IDs ativos, diff e findings, descarte outputs brutos antigos e continue apenas com autoridade.
 10. Falha operacional transitória recebe retry limitado; impedimento essencial deixa a Task `blocked`; falha lógica exige correção localizada ou repair/rework explícito. Antes de uma próxima correção, carregue o [ciclo de correção e bloqueio](references/correction-cycle.md). Nunca esconda uma tentativa.
 
 Recuperação de SPEC materializada com versão de pnpm defasada e Task bloqueada sob release frozen usa somente as prévias e operações atribuídas `spec revise-implementation` e `task recover-release` descritas em [recuperação controlada](references/controlled-release-recovery.md). Decision humana operacional exata, Run/turno observados, journal e refreeze são obrigatórios. O grant permite somente a retomada da Task alvo; audit/publicação continuam bloqueados até novo freeze e qualificação.
@@ -79,9 +87,9 @@ Recuperação de SPEC materializada com versão de pnpm defasada e Task bloquead
 2. Com `autonomy.version: 1`, aplique `RULE-AUTONOMY-DECISION` e seu ledger estável por Task. A seleção manual fica no principal avulso; subagentes seguem política automática com aviso. Sem esse bloco, preserve `automatic_sources` legado (`spec`,`prd`). Não alegue enforcement de orçamento/modelo em ferramenta nativa que não passou pelo dispatch gerenciado.
 3. Em autonomia, exija raiz Git limpa, worktree registrada por Task, commit final canônico sem alterações pendentes, diff dentro dos write scopes e merge abortável em conflito. A integração cria outro commit canônico por Task no histórico first-parent e referencia o SHA do candidato em `ZAIP-Product-Commit`.
 4. Use o menor paralelismo entre projeto, plano, provider e squad. Em `autonomy-v1`, orçamento por Task vem exclusivamente do preset congelado: Essencial 4/1, Equilibrado 10/3, Persistente ilimitado (execuções/replans); tempo não encerra Task. Risco/domain definem assurance, não esse orçamento. Só no contrato legado use as quotas anteriores por risco.
-5. Checkpoints opacos ficam somente em `.local`; não copie token de retomada para records rastreados. Critical recebe contexto fresco e verificador independente.
+5. Checkpoints opacos ficam em `.agents/private/state/checkpoints/`, fora de Git e distribuição; não copie token de retomada para records rastreados nem para `.local` descartável. Critical recebe contexto fresco e verificador independente.
 6. A validação tipada acontece dentro da worktree no commit candidato antes da integração. Falha de assurance não pode ser convertida em sucesso pelo coordenador.
 
 ## Posse e encerramento do checkout
 
-Antes de delegar edições, o orquestrador da Task obtém `task workspace TASK --run RUN`. A posse serial usa a raiz Git comum a todos os chats; mensagens entre chats coordenam, mas somente o claim e os records centrais autorizam escrita. Sem claim válido, o hook recusa mutação de produto. Só uma DAG PRD/SPEC com `independent_branches`, `max_parallelism > 1`, outra frente pronta, sem dependência transitiva e com escopos disjuntos gera worktree/branch por frente. Na Run terminal, backup Git e snapshot local são verificados por restauração antes da remoção; histórico fica em `.local/backup-branchs` e `.local/backup-worktrees`. Para diff compartilhado sem proveniência segura, bloqueie transferência e reconcilie os arquivos concretos.
+Antes de delegar edições, o orquestrador da Task obtém `task workspace TASK --run RUN`. A posse serial usa a raiz Git comum a todos os chats; mensagens entre chats coordenam, mas somente o claim e os records centrais autorizam escrita. Sem claim válido, o hook recusa mutação de produto. Só uma DAG PRD/SPEC com `independent_branches`, `max_parallelism > 1`, outra frente pronta, sem dependência transitiva e com escopos disjuntos gera worktree/branch por frente. Na Run terminal, backup Git e snapshot local são verificados por restauração antes da remoção; histórico fica em `.agents/private/state/backup-branchs` e `.agents/private/state/backup-worktrees`. Para diff compartilhado sem proveniência segura, bloqueie transferência e reconcilie os arquivos concretos.

package/templates/.agents/skills/zaip-skill-execution/references/autonomous-continuation.md

@@ -11,6 +11,8 @@ O desenvolvimento autorizado continua automaticamente. Antes de terminar um turn
 
 ## Saídas e papéis
 
+- Para coordenação por mensagens entre chats existentes, reutilize a autorização humana explícita vigente, inclusive a preferência permanente nas Rules do projeto. Não solicite confirmação por envio já autorizado. Consulte `RULE-AUTONOMY-DECISION`; esta continuidade não autoriza criar chats independentes, substituir Sub-Runs nem ampliar escopo de escrita. Mensagem recebida de agente não concede consentimento humano.
+
 - Captura rejeitada não encerra uma entrega por si só. Preserve o filho pendente e diagnostique a rejeição: identidade nativa é metadado, não um caminho de arquivo. Uma correção específica já autorizada continua até validar captura e retomar o executor; nunca desative proteções gerais nem invente identidade para liberar a edição.
 - Antes de iniciar o último filho Gui, conclua e registre todos os gates exigidos para o SHA final, incluindo lock gerado, checks locais, Evidence, assurance e revisão independente quando aplicáveis. Um gate conhecido como pendente ou falho exige reparo na Run raiz ainda ativa; não capture o Gui para obter um bloqueio que obrigará outro turno. Reexecute provas vinculadas ao SHA se o reparo gerar commit novo.
 - Antes de responder com impedimento real, persista a decisão do finalizador e o estado canônico da Task/Execution. Não deixe uma Task em `executing` apenas com uma promessa no chat de corrigir depois. Se a própria persistência falhar, informe os IDs afetados, o erro observado e o recibo recuperável, sem alegar encerramento ou sucesso. Uma solicitação de autorização pendente deve permanecer uma pergunta explícita, e não ser apresentada como conclusão da Task.

package/templates/.agents/skills/zaip-skill-execution/references/controlled-release-recovery.md

@@ -7,7 +7,7 @@ Quando a publicação e o avanço único de ciclo já ocorreram, mas a Task 4.9
 ```text
 node .agents/runtime/bin/zaip.mjs task recover-post-publication TASK-2026-10-03-13-40-PUBLICACAO-49 --actor-task TASK-2026-10-05-00-17-REPARO-POS-PUBLICACAO-49-FMCRW5CDK3 --actor-execution EXEC-2026-10-05-00-17-DELIVERY-NEW-WORK-EFX3MNZ9WN --run RUN-2026-10-05-00-17-REPARO-POS-PUBLICACAO-49-7K4R7ZVMDM --expected-revision 28 --evidence EVD-ID --json
 node .agents/runtime/bin/zaip.mjs task recover-post-publication TASK-2026-10-03-13-40-PUBLICACAO-49 --actor-task TASK-2026-10-05-00-17-REPARO-POS-PUBLICACAO-49-FMCRW5CDK3 --actor-execution EXEC-2026-10-05-00-17-DELIVERY-NEW-WORK-EFX3MNZ9WN --run RUN-2026-10-05-00-17-REPARO-POS-PUBLICACAO-49-7K4R7ZVMDM --expected-revision 28 --evidence EVD-ID --decision DEC-HUMAN-ID --apply --json
-node .agents/runtime/bin/zaip.mjs task resume-post-publication TASK-2026-10-03-13-40-PUBLICACAO-49 --receipt .local/recovery/post-publication/RECEIPT-HASH.json --json
+node .agents/runtime/bin/zaip.mjs task resume-post-publication TASK-2026-10-03-13-40-PUBLICACAO-49 --receipt .agents/private/state/recovery/post-publication/RECEIPT-HASH.json --json
 ```
 
 Substitua `EVD-ID` pelo ID real de cada Evidence selecionada (se houver múltiplas, separe os IDs por vírgula no mesmo `--evidence`) e `RECEIPT-HASH` pelo nome devolvido pela **aplicação**; a prévia ainda não emite recibo. O primeiro comando é somente leitura. Depois da emissão, finalize normalmente a Task de manutenção e seu Gui; só então execute `resume-post-publication` na mesma invocação humana observada ou em um novo turno autenticamente observado no mesmo thread. A CLI retoma a Execution e a SPEC originais com a Task bloqueada como único alvo. Ela revalida revisões, Decision humana e de emissão, ausência de proprietário, SHA candidato, cada commit até o SHA publicado, Evidence/Validation e observação canônica, CI push em main, Release/tag/asset, npm version/latest/SRI e bytes do tarball, Actions de publicação, origin e hash exato do ciclo. Escrita de produto pela Task histórica continua vedada; complete apenas metadados de fechamento, Evidence, revisão independente quando aplicável e o Gui novo, sem apagar os registros históricos.
@@ -16,8 +16,14 @@ Para rollback operacional antes do consumo, deixe o recibo não consumido e a Ta
 
 ## Grant pendente após interrupção
 
+### Continuação da mesma macro de release congelada
+
+`task recover-release` também aceita a raiz de entrega SPEC sucessora observada no mesmo chat. A raiz deve continuar a Execution original, exigir finalizador e apontar para a raiz anterior terminal; o coordenador terminal registrado no ciclo congelado deve pertencer exatamente àquela raiz e à Task alvo. Outra SPEC, outro chat, predecessor ativo ou coordenador ativo não concede recuperação. Retome a Execution pelo comando público quando estiver bloqueada, capture a continuação e faça prévia + Decision humana com payload exato + aplicação. A autorização já dada pelo usuário pode fundamentar essa Decision; não peça uma confirmação repetida. O grant permanece exclusivo à Task bloqueada, sem aprovar evidências antigas, dispensar refreeze ou alterar as Tasks concluídas.
+
 Quando uma Task já retomou, mudou de revisão e voltou a ficar bloqueada antes do refreeze, use `task recover-release TASK --renew-grant --actor-execution EXEC --run RUN --expected-revision N --json`. A prévia exige o mesmo alvo Task/SPEC/Execution/release, um novo responsável observado e o responsável anterior terminal. A aplicação mantém a Decision humana exata, acrescentando `--decision DEC-HUMAN-ID --apply`; o payload inclui o hash do grant anterior e o estado atual. A CLI não altera a revisão da Task para acomodar o grant.
 
+A renovação também aceita a raiz delivery sucessora da mesma macro com ciclo aberto e grant pendente. A cadeia de continuações até o ator do grant deve conter somente raízes terminais do mesmo chat, SPEC e Execution, sem ciclos e com limite de 32 vínculos. Isso permite uma retomada após turnos de diagnóstico interrompidos; não concede autoridade a outra macro nem dispensa a Decision exata, ausência de proprietário ativo ou revisão vigente.
+
 O journal preserva o grant anterior e o novo. Replay da operação antiga não renova autorização. Revisões concorrentes, outro alvo ou proprietário ativo continuam recusados. `--renew-grant` não libera outras Tasks nem dispensa `task workspace`, refreeze, qualificação ou finalizador. A operação pública de renovação aceita a raiz de interaction sem Task já suportada pelo fluxo de recuperação; portanto não exige criar outra Task para corrigir um grant pendente.
 
 ## Leitura de conteúdo externo no PreToolUse
@@ -31,13 +37,13 @@ Esta operação pública resolve um snapshot de pnpm desatualizado numa SPEC já
 O ator pode ser a Run raiz ativa de uma Task de manutenção em execução (`--actor-task`) ou uma Run raiz de interaction ativa sem Task. Ambos passam `--actor-execution` e `--run`; a CLI compara a sessão e o turno observados com a Run, além da ancestralidade e da Execution. A Task alvo deve estar `blocked`, sem Run proprietária ativa, com predecessoras concluídas. A Decision operacional precisa ser humana, confirmada, vinculada à Change de manutenção ou à Execution da interaction, categoria `contract`, e conter exatamente o JSON `authorization_payload` da prévia. Uma Decision narrativa de escopo geral não substitui esse vínculo.
 
 ```text
-zaip spec revise-implementation SPEC-ID --target-task TASK-ID --actor-task TASK-MANUT --actor-execution EXEC-MANUT --run RUN-MANUT --expected-revision N --implementation .local/proposal.json --json
-zaip spec revise-implementation SPEC-ID --target-task TASK-ID --actor-task TASK-MANUT --actor-execution EXEC-MANUT --run RUN-MANUT --expected-revision N --implementation .local/proposal.json --decision DEC-HUMAN-ID --apply --json
+zaip spec revise-implementation SPEC-ID --target-task TASK-ID --actor-task TASK-MANUT --actor-execution EXEC-MANUT --run RUN-MANUT --expected-revision N --implementation .local/temp/proposal.json --json
+zaip spec revise-implementation SPEC-ID --target-task TASK-ID --actor-task TASK-MANUT --actor-execution EXEC-MANUT --run RUN-MANUT --expected-revision N --implementation .local/temp/proposal.json --decision DEC-HUMAN-ID --apply --json
 zaip task recover-release TASK-ID --actor-task TASK-MANUT --actor-execution EXEC-MANUT --run RUN-MANUT --expected-revision N --json
 zaip task recover-release TASK-ID --actor-task TASK-MANUT --actor-execution EXEC-MANUT --run RUN-MANUT --expected-revision N --decision DEC-HUMAN-ID --apply --json
 ```
 
-No caminho sem Task de manutenção, omita `--actor-task` e use a Execution da interaction em `--actor-execution`. Faça prévia de cada ação, registre uma Decision operacional distinta com o payload exato e só então aplique. O journal limitado em `.local/recovery/` conserva hashes e textos antes/depois, ator e Decision. Repetir a mesma aplicação devolve o resultado já aplicado; se a escrita interrompeu após o journal, a mesma chamada retoma apenas se o conteúdo original e a Run ativa ainda corresponderem. Conteúdo independente divergente bloqueia replay.
+No caminho sem Task de manutenção, omita `--actor-task` e use a Execution da interaction em `--actor-execution`. Faça prévia de cada ação, registre uma Decision operacional distinta com o payload exato e só então aplique. O journal limitado em `.agents/private/state/recovery/` conserva hashes e textos antes/depois, ator e Decision. Repetir a mesma aplicação devolve o resultado já aplicado; se a escrita interrompeu após o journal, a mesma chamada retoma apenas se o conteúdo original e a Run ativa ainda corresponderem. Conteúdo independente divergente bloqueia replay.
 
 `recover-release` muda `frozen` para `open` com um grant que admite apenas `task resume` da Task/SPEC/Execution autorizadas. A Task continua bloqueada até sua retomada pública sob proprietário legítimo. Outras Tasks não podem iniciar enquanto o grant existir. O refreeze consome o grant somente pela mesma Task de coordenação delegada da SPEC, validada pela política de release existente; o audit e o advance recusam grant pendente. O novo candidato precisa ser qualificado e revisado no SHA final depois desse refreeze. Nenhuma prova histórica é aprovada retroativamente.
 

package/templates/.agents/skills/zaip-skill-execution/references/conversation-promotion.md

@@ -0,0 +1,38 @@
+# Promoção tipada de conversa
+
+Se o mesmo turno humano autorizado foi capturado como `conversation`, preserve
+seu Run/Execution e use `conversation start --intent continue --task TASK-ID
+--promote-conversation RUN-CONVERSATION --direct-authorization "TEXTO HUMANO
+OBSERVADO" --json`. Não solicite outra mensagem apenas para corrigir o modo.
+
+A CLI valida principal nativo, thread/turno, modelo/esforço, conversa ainda aberta
+sem alvo ou filhos, Task-first executável da versão atual, foco/alvo e instrução
+literal. A claim tipada fecha somente a interação vazia, mantém a invocação física
+e inicia entrega com os gates/finalizador normais. Repetição idêntica reutiliza
+IDs. Authority ausente, alvo ambíguo, terminal, delegação existente, modelo
+divergente, release congelada e contrato desconhecido permanecem bloqueios reais.
+
+Para trabalho novo autorizado, use `--intent new-work`, `--title`, `--short-name`,
+`--objective`, `--write-scopes` e os mesmos argumentos de promoção/autorização.
+Title/objective devem ser trechos literais da instrução observada. A reserva em
+`.agents/private/state/claims/conversation-new-work/` fixa IDs e hash; o materializador canônico
+retoma uma interrupção sem outro Task. Não edite a reserva ou o plano para mudar
+o escopo. A saída inclui `assurance_planning`; cumpra suas obrigações.
+
+Registrar SQL confirmado em configuração não autoriza executar SQL. Promoção
+não concede deploy/publicação: a skill de deploy exige sua autorização já
+observada e alvo exato. Histórico indisponível não é prova de autorização.
+SPEC/PRD e handoffs pós-publicação conservam seus comandos específicos. Em
+falha desconhecida, informe causa e comando de diagnóstico, sem inventar turno.
+
+Instruções observadas como “Pode seguir com a implementação da TASK-ID. Não
+publique” são reconhecidas preservando o texto integral e suas restrições.
+Perguntas, hipóteses, citações e negações da ação continuam recusadas.
+Se a retomada foi interrompida depois do fechamento da interação e antes da
+criação do sucessor, repita a mesma promoção: o recibo existente fixa os IDs.
+Não capture outro turno nem crie outra Task para corrigir essa interrupção.
+
+No cenário SQL/deploy, primeiro registre somente a configuração confirmada.
+Recuperar lifecycle não executa SQL nem comprova deploy. Teste configuração,
+permissões e estados de retomada com fixtures/sandbox; efeitos externos exigem
+autoridade própria e prova do resultado antes de serem declarados concluídos.

package/templates/.agents/skills/zaip-skill-execution/references/runtime-governance.md

@@ -17,6 +17,8 @@ Carregue antes de executar uma entrega ou delegar. Este contrato detalha o kerne
 
 ## Limites do host e relay de persistência
 
+- Se um subagente continuar em outro turno físico enquanto seu Run canônico permanece aberto, use `run continue-subagent` com os IDs exatos de Run, pai, responsável, Task/Execution/SPEC, sessão nativa, turno anterior e turno observado. O host autentica o contexto do principal e a cadeia nativa antes de emitir um recibo de continuação imutável; não edite recibos, correlações ou o evento inicial. Essa ponte não cria Task, tentativa, reserva, grant ou novo responsável. Uma sessão, identidade, modelo ou ancestralidade divergente, um predecessor ainda ativo ou um Run já encerrado não autoriza continuação. Depois da retomada autenticada do responsável, `run continue-principal` pode vincular o novo turno do principal. A captura final usa o turno efetivo comprovado e preserva o histórico original.
+
 - Gui pode ser o último filho para avaliar uma entrega que não conseguiu iniciar executor. Isso não concede sucesso: `executor_missing` mantém `completed` bloqueado mesmo com Evidence aprovada; decisões reais `blocked`/`failed` seguem o relay normal e preservam o motivo. Não crie executor cerimonial para satisfazer o fechamento. A exceção direta continua restrita à raiz Task autorizada desde a captura.
 
 - `execution.runtime: managed` despacha PRD/SPEC pelo provider e mantém avulsas diretas. Para a raiz Task direta, registre a referência humana em `--direct-authorization` desde a captura. Identidade e intenção sozinhas não concedem autorização. Esse contrato substitui somente o executor filho; nunca Evidence, revisão aplicável, Gui ou identidade observada. Não autorize retroativamente uma raiz fechada, macro ou filho.
@@ -24,7 +26,7 @@ Carregue antes de executar uma entrega ou delegar. Este contrato detalha o kerne
 - Há exatamente um orquestrador responsável por tentativa de Task. Quando a raiz física já é Task-scoped, ela despacha executor/revisor e Gui diretamente: não inicia um Dave adicional. Somente uma raiz macro delega orquestradores de Tasks distintas; seus trabalhadores e Gui pertencem ao respectivo orquestrador. Coordenação e aceite parental não representam uma segunda tentativa da mesma Task.
 - Os nomes de ferramentas no catálogo são capacidades, não nomes literais de ferramentas do host. O orquestrador pode descobrir ferramentas diferidas no registro nativo e usar spawn/send/wait/close dos descendentes autorizados, inclusive com filesystem read-only. Essa permissão não autoriza persistência pelo perfil, chats independentes ou ampliação de sandbox. Declarar indisponibilidade exige conferir o registro efetivamente exposto.
 
-- `agent_type` usa o `codex_name` exato. Envie `task_name` somente se o schema da ferramenta nativa o oferecer; nesse caso use o `codex_task_name` exato. Sem esse parâmetro, use o perfil catalogado e preserve o UUID/nickname retornado, inclusive sufixos atribuídos pelo host. Nunca transforme UUID ou nickname em `agent_path` nem use nome como prova de ancestralidade.
+- `agent_type` usa o `codex_name` exato. Envie `task_name` somente se o schema da ferramenta nativa o oferecer; nesse caso use o `codex_task_name` exato. Exceção estreita: uma reserva causal autenticada pode emitir `invocation.task_name`; use somente esse nome exato para essa invocação, sem inventar sufixos e mantendo `codex_name` e o nome-base do catálogo. Sem esse parâmetro, use o perfil catalogado e preserve o UUID/nickname retornado, inclusive sufixos atribuídos pelo host. Nunca transforme UUID ou nickname em `agent_path` nem use nome como prova de ancestralidade.
 - Orquestrador e Gui com perfil `read-only` não executam comandos que escrevem records, locks ou recibos. Eles retornam eventos e decisão ao host autorizado. O host é o escritor do lifecycle, não um executor/finalizador substituto: não altera a decisão, identidade, pai ou evidências do agente.
 - A ordem canônica é início real, decisão observada de Gui, Stop e fechamento com a mesma decisão. Não imponha ao Gui espera ativa por recibos: ele pode devolver seu resultado terminal; o host usa `subagent capture --event stop` com a decisão real nos campos `task-outcome`, `summary`, `evidence`, `changed-files`, persistindo-a antes do Stop canônico. O relay rico aceita filho já terminal com responsável aberto, sem trocar metadados por fallback. Responsável fechado sem decisão exige nova tentativa autorizada. Não confunda horário observado com gravação, nem status nativo com decisão.
 - O fallback `capture-terminal` continua restrito ao contrato de path, pai e identidade já descrito. UUID com `agent_path: null` não satisfaz esse fallback. Falta de prova rica, conflito de ancestry ou falha do escritor bloqueia a entrega, sem recriar Tasks, inventar metadados, ampliar sandbox ou pedir a um executor que delegue Gui.

package/templates/.agents/skills/zaip-skill-external-integrations/SKILL.md

@@ -12,3 +12,5 @@ Use for outbound providers, inbound webhooks, or vendor protocol changes.
 3. Verify signatures before processing webhooks, use stable event identities for deduplication, and retain a bounded replay path.
 4. Place provider behavior behind an adapter and use sanitized fixtures for success, timeout, invalid response, and duplicate event cases.
 5. Do not enable production callbacks or mutate a provider account without explicit external authorization.
+
+For Kommo, compose the [discovery and recovery runbook](references/kommo.md) and [measurement contract](../zaip-skill-lead-measurement/references/kommo-contract.md). Complete authorized pagination and visibility checks before interpreting absence; ambiguous/incomplete matching never creates a contact automatically. Preserve manual CRM decisions and distinguish delivery leases from contact/destination coordination. The disabled API example is documentation, not an authenticated integration.

package/templates/.agents/skills/zaip-skill-external-integrations/references/kommo.md

@@ -0,0 +1,71 @@
+# Kommo — descoberta, política e recuperação
+
+Owner: mantenedor de external-integrations; revisão documental 2026-10-29. Conta/empresa/operador e aprovação de adoção permanecem pendentes. Este é um runbook portável: nenhum SQL, HTTP/CRM, credencial, conta, consumidor, adapter ou backend foi acessado/criado. O exemplo [kommo-crm](../../../tools/api/kommo-crm/README.md) permanece desabilitado. Compor [contrato de mensuração](../../zaip-skill-lead-measurement/references/kommo-contract.md), [identidade](../../zaip-skill-lead-measurement/references/identity-contract.md) e [delivery v2](../../zaip-skill-lead-measurement/references/delivery-contract.md).
+
+## Descoberta antes de qualquer efeito
+
+Registrar tenant/ambiente e host HTTPS exato da conta, proprietário/operador, autorização, versão do mapa e capacidades da sessão. Conta conectada diferente, nome comercial ou subdomínio recebido do formulário não concedem destino. GET /api/v4/account ajuda a identificar conta, mas não comprova escrita nem visibilidade integral de contatos. Paginar inventário e distinguir zero, parcial, forbidden, erro e indisponibilidade.
+
+Inventariar pipelines/etapas, carteiras, responsáveis/usuários, campos customizados/enums, tags, filtros e campos de correlação existentes. Guardar IDs/versionamento server-owned, nunca aceitar host/pipeline/owner do formulário. Conferir operações/schema pela ferramenta/documentação vigente antes de escrever; nomes de tool/labels de UI não são inventados pelo runbook. Inexistência de capacidade deixa operação exata pendente; não habilitar manifest ou ampliar credencial por default.
+
+Descobrir contratos publicados, contatos compartilhados, oportunidades recorrentes e regras de negócio. Contato existente não significa solicitação duplicada; nova ocorrência não é autorização automática para nova oportunidade. Aprovar conta, BANT, match, finalidade/retention e transições por empresa antes da adoção.
+
+## Autenticação: caminhos distintos
+
+| Caminho futuro | Procedimento e autoridade | Parada/recuperação |
+| --- | --- | --- |
+| OAuth2 | Titular autoriza integração e escopo; validar state, redirect e vínculo da conta conforme fluxo oficial vigente; guardar tokens só no cofre/backend | Expiração/refresh/rotação seguem resposta e contrato atuais; serializar refresh e persistir material novo por mecanismo autorizado, sem logs ou replay de código |
+| Long-lived token | Integração privada para a própria conta, direitos do emissor e validade escolhida/observada | Não possui refresh_token; expiração/revogação/rotação exigem procedimento próprio, não chamar fluxo OAuth de refresh como fallback |
+
+Token de outro serviço/conta ou acesso de leitura não é credencial de escrita. Identidade de serviço, privilégios mínimos e delivery por ambiente seguem a política do backend/cofre autorizado. 401 pede diagnóstico de autenticação; 403 pode indicar direitos/limite/restrição e não ausência de contato. Não imprimir Authorization, refresh token, erro bruto ou URL com contato. Não acessar credenciais durante C08.
+
+## Paginação, busca e ausência
+
+GET /api/v4/contacts e GET /api/v4/leads respeitam direitos/filtros; query pode pesquisar campos customizados (exemplo oficial por telefone), mas resultado de busca não prova igualdade normalizada. Depois de buscar candidatos, aplicar comparação exata segundo política aprovada e registrar cobertura. Não remover plus/dots de e-mail ou inferir equivalência universal; não tratar telefone parcial como pessoa única.
+
+Seguir todas as páginas necessárias, confirmando host/path/conta, filtros estáveis, cursor/progresso e conclusão sem erro. page/limit até250 é tamanho de página, não teto de inventário; política pode exigir várias páginas. Próximo link/cursor cross-host ou repetido, cap operacional atingido, página perdida, erro, 429, resposta inválida ou visibilidade desconhecida tornam resultado **incomplete**, mesmo com zero candidatos na primeira página. Nunca encaminhar bearer em redirect cross-host.
+
+Deduplicar a mesma entidade externa repetida em páginas somente se ID/conteúdo relevante forem consistentes. IDs distintos que atendem à política são ambiguidade; mesmo ID com dados conflitantes pede releitura/revisão. Busca completa sem correspondência resulta apenas ausência **dentro do escopo autorizado e visível**, sem alegar ausência global ou pessoa nova. Snapshot pode mudar enquanto se pagina: documentar consistência/progresso e revalidar antes de um efeito; não prometer snapshot atômico remoto.
+
+## Match e decisões comerciais
+
+Estados normalizados: unique, ambiguous, incomplete e absent_within_authorized_scope. Apenas unique identifica candidato segundo política; não autentica pessoa nem autoriza create/update. Demais estados não elegem o primeiro resultado e nunca acionam create automático. Mesmo ausência qualificada exige decisão explícita/configuração aprovada para qualquer nova entidade, fora deste pacote documental.
+
+| Situação descoberta | Decisão por empresa a aprovar | Proteção constante |
+| --- | --- | --- |
+| Ganho/carteira existente | Skip/review/nova oportunidade conforme processo real | Não trocar carteira/responsável nem reabrir por default |
+| Ativo no funil-alvo ou em outro | Atualizar campos permitidos, revisar ou preservar conforme política | Não rebaixar estágio/mover funil silenciosamente |
+| Perdido | Reabrir/criar/revisar somente com regra específica | Preservar histórico e ação manual |
+| Ausente/ambíguo/incompleto | Ausência pode preparar proposta; ambiguidade/incompletude exigem revisão/continuação de leitura | Nenhum create automático; nenhum fallback por erro |
+
+Questionário/regra e mapping têm versões separadas; alteração não recalcula histórico nem substitui override humano. MQL que exige decisão solo, se adotado por uma empresa, é regra daquela empresa/CRM. Authority shared pode ser elegível para métrica Meta sob outra regra; não impor MQL global ou reinterpretar uma métrica como a outra. Notificar drift comercial e parar transição, preservando cadastro aceito.
+
+## Escrita futura: patch mínimo e checkpoints
+
+Manter estado por suboperação: discovery/match → contato confirmado → lead confirmado → vínculo confirmado → campos/tags confirmados → transição comercial autorizada → complete. Antes de cada efeito, persistir intenção, alvo, IDs conhecidos, payload fingerprint restrito, versão e checkpoint; depois validar resposta/contexto/efeito e confirmar checkpoint próprio. HTTP2xx/request_id local não provam efeito nem idempotência remota. Resposta HAL+JSON/problema e campos reais devem ser validados pelo adapter antes de normalizar.
+
+Patch deve ser allowlist: valores null não apagam conhecidos; atualizações técnicas não substituem carteira, responsible, pipeline/status, tags comerciais ou manual_override. Adicionar somente tags técnicas aprovadas por operação suportada, sem trocar lista inteira. Se API oferecer apenas replacement sem garantia de preservar concorrência, reler/reconciliar ou parar; não simular CAS/ETag que não foi comprovado. Transição comercial é suboperação distinta, explicitamente autorizada, com leitura atual e respeito ao override.
+
+Falha após contato criado não repete criação ao retomar lead/link/fields. Confirmar IDs externos como strings, vínculo da ocorrência/contato/conta e estado real antes de avançar. IDs conhecidos divergentes nunca são sobrescritos pelo último resultado. Timeout após POST/PATCH/link é uncertain: reconciliar por vínculos/ID/correlação aprovada e leitura suficiente antes de retry. Se não existir mecanismo seguro de provar ausência/efeito, permanecer em revisão; não inventar idempotência nativa ou procurar só por request_id local.
+
+## Concorrência: duas fronteiras
+
+Lease/fence por entrega protege um item/worker e suas atualizações locais. Coordenação por contato+destino físico protege operações de entregas distintas que podem criar/alterar a mesma entidade CRM. Chave inclui tenant/ambiente/conta-recurso e identidade de contato aprovada; alias destination_id/mapping novo não deve contornar a mesma fronteira física. Subrecursos que tocam a mesma entidade precisam compartilhar coordenação adequada.
+
+Manter exclusão/coordenador durável com owner/fence e recuperação, sem transação DB aberta durante HTTP. Lease expirada ou worker antigo não pode confirmar checkpoint de outro fence; efeito remoto tardio pode já ter ocorrido e exige reconciliação antes de novo create. Esse mecanismo não bloqueia operador humano no CRM; leitura/checkpoint/versionamento não são CAS remoto por si. Preservar campos protegidos e parar em drift manual; não prometer exactly-once global ou concorrência provada por documento.
+
+## Limites, retry e retomada
+
+Referência pública:7requisições/s; confirmar escopo efetivo de orçamento/headers na adoção e compartilhar limite entre workers, sem contornar com paralelismo por job. Até250 entidades por página/update batch não é inventário completo. 429 respeita Retry-After válido e backoff/jitter limitados; não antecipar para caber no cap. Reincidência pode resultar403. Falha de leitura retoma cursor seguro após a espera, sem promovê-la a ausência.
+
+Em escrita, decidir retry só após classificar ausência de efeito; timeout/lease expirada/resultados ambíguos exigem reconciliação. Tentativas e janela são aprovadas e limitadas; esgotamento/erro permanente isolam a suboperação, preservando IDs/checkpoints e os outros eventos. Refresh OAuth, problema de permissão e rate limit têm diagnósticos diferentes; nenhuma falha autoriza novo contato/lead como compensação.
+
+## Operação manual, evidência e rollback
+
+Sem capacidade API adequada, preparar ficha não secreta com host/conta confirmados, inventário, mapping e decisão pendente. Operador autorizado verifica páginas/visibilidade, candidatos, carteira/owner/estágio/tags e checkpoints na interface vigente; registra decisão/resultado no controle restrito autorizado. Ação manual não pode ficar invisível ao ledger nem substituir integração durável por uma sequência sem retomada. Labels/schema não observados permanecem campos específicos pendentes com owner.
+
+Fixtures K01–K13 do [contrato](../../zaip-skill-lead-measurement/references/kommo-contract.md) são documentais, não executadas. C08 usa inspeção estática de cenários/links, regressão C05 apenas complementar e review independente. OAuth/conta/CRM/concorrência/preservação remota não foram testados. Rollback desta entrega é textual; rollback futuro pausa novos efeitos e reconcilia os existentes, sem excluir contatos/leads ou apagar checkpoints para reenviar.
+
+## Fontes e manutenção
+
+Fontes públicas verificadas pelo host em 2026-10-29, sem conta/grants observados: [conta](https://developers.kommo.com/reference/account-parameters), [contatos](https://developers.kommo.com/reference/contacts-list), [leads](https://developers.kommo.com/reference/leads-list), [OAuth2](https://developers.kommo.com/docs/oauth-20), [long-lived token](https://developers.kommo.com/docs/long-lived-token), [limites](https://developers.kommo.com/docs/limitations). Revalidar UI/schema/permissões/limites antes da adoção, após mudança de API/política ou incidente; registrar owner/data/candidato e limite de cada prova.

package/templates/.agents/skills/zaip-skill-figma-setup/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: zaip-skill-figma-setup
+description: Inspect or configure Figma access when the user requests Figma setup; verify listed tools, authentication and target access separately.
+---
+
+# Prepare Figma access
+
+Use this entry for setup and access diagnosis. A Figma reference alone does not select
+the designer or authorize editing a file.
+
+1. Read the shared contracts below and inspect the host's available Figma connector
+   and installed official plugin skill. Load the official prerequisite before its tool.
+2. Distinguish tool listed, server configured, authenticated, target readable,
+   structured context available, screenshot available, and write permission. Missing
+   capabilities stay unavailable; setup does not prove login or file access.
+3. Prefer the host's official remote plugin/OAuth workflow. Desktop MCP is a separate
+   optional route. Do not hardcode personal cache paths, install silently, or expose tokens.
+   Follow [the connection guide](references/figma-connection.md) for the actual Codex
+   setup steps, remote endpoint and optional desktop route. Documentation consulted
+   is not authentication observed; configuration/OAuth is conditional on host authority.
+4. Request only a missing frame/node target needed to verify access; never guess a node.
+5. Return a capability report with observed locators and next action. Configuration or
+   authentication changes require the already-authorized host capability; this contract
+   does not grant external write permission. No Figma/product mutation follows setup.
+6. Route a report, faithful reproduction, or standardized implementation by its output
+   and destination. For implementation obtain structured context and a reference screenshot,
+   variable/component mappings and assets where available; record sparse fields as unknown.
+   Apply [the Figma handoff contract](references/figma-handoff.md): exact file/node,
+   sparse child fetches, accessible required assets and exact-node Code Connect.
+
+The installed workflow uses these portable references and the host's tools. It does
+not require a maintainer package, test runner or sibling checkout. Without a supplied
+live file/node, provide a capability report with conditional target-access limits and
+request a target only for requested live use. Do not select a delivery role from Figma input.
+
+Do not claim real OAuth, file access or rendered fidelity from fixtures.
+
+## Shared contracts
+
+Read [source-contract](../zaip-skill-visual-report/references/source-contract.md),
+[intake-state](../zaip-skill-visual-report/references/intake-state.md) and
+[fidelity-proof](../zaip-skill-visual-report/references/fidelity-proof.md) before using this entry.

package/templates/.agents/skills/zaip-skill-figma-setup/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "ZAIP Figma Setup"
+  short_description: "Verify Figma tools, access and target readiness."
+  default_prompt: "Use $zaip-skill-figma-setup to inspect Figma access and setup capabilities for the requested target."
+policy:
+  allow_implicit_invocation: true

package/templates/.agents/skills/zaip-skill-figma-setup/references/capability-contract.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": 1,
+  "capabilities": [
+    "plugin_installed",
+    "server_configured",
+    "tools_listed",
+    "authenticated",
+    "target_readable",
+    "structured_context",
+    "initial_screenshot",
+    "assets_accessible",
+    "code_connect",
+    "write_permission"
+  ],
+  "capability_states": ["unknown", "available", "unavailable", "error"],
+  "target_capabilities": [
+    "target_readable",
+    "structured_context",
+    "initial_screenshot",
+    "assets_accessible",
+    "code_connect"
+  ],
+  "observation_fields": ["state", "origin", "locator", "observed_at", "reason", "target"],
+  "origins": ["host", "fixture"],
+  "connection_routes": ["plugin-remote", "remote-mcp", "desktop-mcp", "none"],
+  "remote_endpoint": "https://mcp.figma.com/mcp",
+  "desktop_endpoint": "http://127.0.0.1:3845/mcp",
+  "handoff_states": ["conditional", "pending", "ready"],
+  "proof_scopes": ["fixture-contract", "host-observations"],
+  "missing_live_target": "conditional-for-requested-live-use",
+  "source_selects_executor": false,
+  "handoff_grants_external_writes": false,
+  "handoff_proves_render_fidelity": false,
+  "official_prerequisites": {
+    "get_design_context": "figma-design-to-code",
+    "use_figma": "figma-use"
+  },
+  "consumer_execution": "host-tools-and-portable-references",
+  "requires_maintainer_package": false
+}