@zaip-ai/cli 3.8.0 → 4.0.0

package/templates/.agents/runtime/checksums.sha256

@@ -1,11 +1,11 @@
 b146bd0c7c60b1ab43c4f71e0b1d2262c6df6da6f7053a0425f834ccb77a6b48  LICENSE
 bc02cba77e8d51e5c580f43668863dc868eda66f1ff663bfaa49fcf3ca16320e  THIRD_PARTY_NOTICES.md
-88206afd2d9b56ca71466c85d1ed1421b1db0e78fa00072697918fb8a9ac54ef  VERSION
-b9d0c02583775ea664f7bb92d73c4c901194d4a9bbd3a49993b4891ed241b6ef  bin/zaip.mjs
-d6ef4cfccc2b5d66289f37da8e3f8c726d2c6f5fe8f93e65b0e1f7df7c9b450d  manifest.json
+e1d49c569ae09b2ede16e2d83820a3809b35eb6c44c13ba9b5330598d6b8f43c  VERSION
+239d00f5ff145dfddbdaee66fa94a286e3e80228bfec8f67919ea6f9099b16a0  bin/zaip.mjs
+57c1b270eed2ecf577dd3e0d13a951380aa96a5a4b5a7adf396f31a1df777e96  manifest.json
 7f89219d7c567c82a51679ad136d84364bded7ac659492537e125d33b1d58a7a  migrations/001-layout-v1.json
 5f8c48b286d0b44d8fbb57a9a5d009a8a500439aa3148d750b8f193f72995c9f  migrations/002-layout-v2.json
 33c98d5dc506bba4b8b3ca612706d9eb05ef13d9e03c33a4f9e65ca7804be9d1  pnpm-lock.sha256
-15a8ac0676b794bf453eb54f027b30c0ca7cc5e7e572c591a5d76dee6efd1ed3  provenance.json
-017f220c51e33ecccbcbeb58a5673b990b67c37b44a5e6761f02be8c9219a761  sbom.cdx.json
+54fc0f67af77dba2941ab13c90eb77afcd61f3ec62b28c2c6a07961c79e540ff  provenance.json
+9bf5a95c277816679d424ff2fb9a99f2e41b4a32c442c95159c314e3c4efe04f  sbom.cdx.json
 b3ffedf9e146be802a15b4009f33e031dec3071ca1525e12c67606fd964a3067  schemas/contracts.schema.json

package/templates/.agents/runtime/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "zaip-aios",
-  "version": "3.8.0",
+  "version": "4.0.0",
   "node": ">=22",
   "files": [
     "LICENSE",

package/templates/.agents/runtime/provenance.json

@@ -2,10 +2,10 @@
   "schema_version": 1,
   "statement_type": "self_reported_build_integrity",
   "authenticity": "unverified",
-  "version": "3.8.0",
+  "version": "4.0.0",
   "source_origin": "zaip-aios:local-build",
   "lockfile_sha256": "03d08e5bbb198d74014ea4a806fcdeb350db23ec2bf0c2886a2265066555d418",
-  "sbom_sha256": "017f220c51e33ecccbcbeb58a5673b990b67c37b44a5e6761f02be8c9219a761",
-  "runtime_sha256": "ce933ca820e864c27fb8fc33c873ef94504cf2015e14cdd8709b6b9e72370bb9",
-  "statement_sha256": "a6b24e3dacdca76511477e9f77a8d83281159cf73d96257b962c6677009f80dd"
+  "sbom_sha256": "9bf5a95c277816679d424ff2fb9a99f2e41b4a32c442c95159c314e3c4efe04f",
+  "runtime_sha256": "3f08dd1f60c42934f982cf368df0610f852a96b19123c8771e85e92cccd24e6e",
+  "statement_sha256": "9c05251add6c72fd1fe61d5353ba239bc693e95a80a03d0389a38b1e6e6f413b"
 }

package/templates/.agents/runtime/sbom.cdx.json

@@ -6,7 +6,7 @@
     "component": {
       "type": "application",
       "name": "zaip-aios",
-      "version": "3.8.0"
+      "version": "4.0.0"
     }
   },
   "components": [

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

@@ -1,18 +1,18 @@
 ---
 name: zaip-skill-executar-fila-pronta
-description: Execute the full eligible ready-work snapshot using the canonical queue order.
+description: Execute one eligible top-level ready item per scheduled Codex invocation.
 ---
 
 # Executar fila pronta
 
-Use esta skill para uma rodada idempotente que processa sequencialmente o snapshot elegível da fila. A seleção é estrita: PRD `ready`, depois SPEC `ready` independente, depois Task-first standalone elegível em `Pronto para Executar`.
+Use esta skill para uma rodada idempotente que reivindica e executa **um único item superior** da fila. A seleção é estrita: PRD `ready`, depois SPEC `ready` independente, depois Task-first standalone elegível em `Pronto para Executar`. Uma rodada jamais inicia um segundo item, mesmo quando o primeiro termina rapidamente, falha ou é pulado por disputa.
 
 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, crie 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`. 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 token e `owner_token` conferidos, antes de cada candidato. Antes de cada efeito (incluindo iniciar uma Execution), releia o lock e exija ambos os tokens atuais e prazo válido; se a renovação falhar ou o token não for atual, encerre a rodada sem executar mais efeitos. Libere somente ao terminar e apenas se o `owner_token` ainda corresponder; locks expirados podem ser substituídos atomicamente.
-4. Forme os candidatos nesta precedência: (a) PRDs `ready`; (b) SPECs `ready` que não descendem de PRD; (c) Tasks 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. Para cada candidata, exclua o registro 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. Exclua também descendentes de PRD/SPEC e itens `active`, `blocked`, `failed`, `cancelled` ou terminais.
-5. Ordene cada classe por `.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 pelo fallback canônico determinístico. Congele o snapshot ordenado e processe todos os PRDs antes de SPECs, e todos os SPECs antes das Tasks; não misture classes.
-6. Execute cada unidade do snapshot, uma por vez, 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. Reavalie o estado antes de cada início e pule o item que deixou de ser elegível. 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 de cada unidade, as omissões e a ausência de candidatos, 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.
+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.
+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.
 
 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,5 +1,6 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 
 export async function acquireReadyQueueFence(lockPath, input) {
   return withMutex(lockPath, async () => {
@@ -19,11 +20,25 @@ export async function acquireReadyQueueFence(lockPath, input) {
 export async function renewReadyQueueFence(lockPath, lease, now, expiresAt) {
   return withMutex(lockPath, async () => {
     if (!(await assertReadyQueueFence(lockPath, lease, now))) return null;
-    const renewed = { ...lease, expires_at: expiresAt };
+    const renewed = { ...(await readLease(lockPath)), expires_at: expiresAt };
     await writeLease(lockPath, renewed);
     return renewed;
   });
 }
+/** A scheduled invocation may claim exactly one canonical top-level item. */
+export async function claimReadyQueueItem(lockPath, lease, itemId, now) {
+  if (!/^(PRD|SPEC|TASK)-[A-Z0-9-]+$/.test(itemId))
+    throw new Error("Ready queue claim requires one canonical item ID");
+  return withMutex(lockPath, async () => {
+    if (!(await assertReadyQueueFence(lockPath, lease, now))) return null;
+    const current = await readLease(lockPath);
+    if (current.claimed_item_id !== undefined && current.claimed_item_id !== itemId) return null;
+    if (current.claimed_item_id === itemId) return current;
+    const claimed = { ...current, claimed_item_id: itemId, claimed_at: now };
+    await writeLease(lockPath, claimed);
+    return claimed;
+  });
+}
 export async function assertReadyQueueFence(lockPath, lease, now) {
   const current = await readLease(lockPath);
   return (
@@ -37,19 +52,29 @@ export async function assertReadyQueueFence(lockPath, lease, now) {
 export async function releaseReadyQueueFence(lockPath, lease, now) {
   return withMutex(lockPath, async () => {
     if (!(await assertReadyQueueFence(lockPath, lease, now))) return false;
-    await writeLease(lockPath, { ...lease, expires_at: now, released_at: now });
+    await writeLease(lockPath, {
+      ...(await readLease(lockPath)),
+      expires_at: now,
+      released_at: now,
+    });
     return true;
   });
 }
 async function withMutex(lockPath, operation) {
   const mutex = `${lockPath}.mutex`;
   await mkdir(dirname(lockPath), { recursive: true });
-  try {
-    await mkdir(mutex);
-  } catch (error) {
-    if (error?.code === "EEXIST") return null;
-    throw error;
+  let acquired = false;
+  for (let attempt = 0; attempt < 25; attempt += 1) {
+    try {
+      await mkdir(mutex);
+      acquired = true;
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (attempt < 24) await delay(40);
+    }
   }
+  if (!acquired) throw new Error(`Ready queue mutex remains held: ${mutex}`);
   try {
     return await operation();
   } finally {

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

@@ -1,11 +1,13 @@
 import assert from "node:assert/strict";
-import { mkdtemp, rm } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import {
   acquireReadyQueueFence,
   assertReadyQueueFence,
+  claimReadyQueueItem,
   releaseReadyQueueFence,
   renewReadyQueueFence,
 } from "./ready-queue-fence.mjs";
@@ -58,3 +60,134 @@ test("fence is exclusive, monotonic, and rejects a stale owner", async () => {
     await rm(directory, { recursive: true, force: true });
   }
 });
+
+test("Windows-compatible lease command allows only one claimed item", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "zaip-ready-cli-"));
+  const script = join(import.meta.dirname, "ready-queue-lease.mjs");
+  const call = (...args) =>
+    JSON.parse(
+      execFileSync(process.execPath, [script, ...args], { cwd: directory, encoding: "utf8" }),
+    );
+  try {
+    await mkdir(join(directory, ".agents", "config"), { recursive: true });
+    await writeFile(
+      join(directory, ".agents", "config", "project.yaml"),
+      "zaip:\n  enabled: true\n",
+    );
+    const lease = call("acquire").result;
+    assert.equal(
+      call("claim", lease.owner_token, String(lease.fencing_token), "TASK-2026-09-24-READY-AAAA")
+        .result.claimed_item_id,
+      "TASK-2026-09-24-READY-AAAA",
+    );
+    assert.equal(
+      call("renew", lease.owner_token, String(lease.fencing_token)).result.claimed_item_id,
+      "TASK-2026-09-24-READY-AAAA",
+    );
+    assert.throws(
+      () =>
+        call("claim", lease.owner_token, String(lease.fencing_token), "TASK-2026-09-24-READY-BBBB"),
+      /Command failed/,
+    );
+    assert.equal(call("release", lease.owner_token, String(lease.fencing_token)).ok, true);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("one lease cannot claim a second ready item, including after renewal", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "zaip-ready-single-"));
+  const lock = join(directory, "ready-queue.lock.json");
+  try {
+    const lease = await acquireReadyQueueFence(lock, {
+      owner_token: "owner-a",
+      now: "2026-09-24T12:00:00.000Z",
+      expires_at: "2026-09-24T12:01:00.000Z",
+    });
+    const claimed = await claimReadyQueueItem(
+      lock,
+      lease,
+      "PRD-2026-09-24-READY-AAAA",
+      "2026-09-24T12:00:01.000Z",
+    );
+    assert.equal(claimed.claimed_item_id, "PRD-2026-09-24-READY-AAAA");
+    const renewed = await renewReadyQueueFence(
+      lock,
+      lease,
+      "2026-09-24T12:00:02.000Z",
+      "2026-09-24T12:02:00.000Z",
+    );
+    assert.equal(renewed.claimed_item_id, "PRD-2026-09-24-READY-AAAA");
+    assert.equal(
+      await claimReadyQueueItem(
+        lock,
+        renewed,
+        "SPEC-2026-09-24-READY-BBBB",
+        "2026-09-24T12:00:03.000Z",
+      ),
+      null,
+    );
+    assert.equal(
+      (
+        await claimReadyQueueItem(
+          lock,
+          lease,
+          "PRD-2026-09-24-READY-AAAA",
+          "2026-09-24T12:00:04.000Z",
+        )
+      ).claimed_item_id,
+      "PRD-2026-09-24-READY-AAAA",
+    );
+    assert.equal(await releaseReadyQueueFence(lock, lease, "2026-09-24T12:00:05.000Z"), true);
+    assert.equal(
+      await claimReadyQueueItem(
+        lock,
+        lease,
+        "PRD-2026-09-24-READY-AAAA",
+        "2026-09-24T12:00:06.000Z",
+      ),
+      null,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("transient mutex contention waits instead of pretending the queue is locked", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "zaip-ready-contention-"));
+  const lock = join(directory, "ready-queue.lock.json");
+  const mutex = `${lock}.mutex`;
+  try {
+    await mkdir(mutex);
+    const pending = acquireReadyQueueFence(lock, {
+      owner_token: "owner-a",
+      now: "2026-09-24T12:00:00.000Z",
+      expires_at: "2026-09-24T12:01:00.000Z",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    await rm(mutex, { recursive: true });
+    assert.equal((await pending)?.owner_token, "owner-a");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("orphaned mutex fails visibly without deleting another owner's lock", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "zaip-ready-orphan-"));
+  const lock = join(directory, "ready-queue.lock.json");
+  const mutex = `${lock}.mutex`;
+  try {
+    await mkdir(mutex);
+    await assert.rejects(
+      acquireReadyQueueFence(lock, {
+        owner_token: "owner-a",
+        now: "2026-09-24T12:00:00.000Z",
+        expires_at: "2026-09-24T12:01:00.000Z",
+      }),
+      /mutex remains held/,
+    );
+    assert.equal((await stat(mutex)).isDirectory(), true);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+  acquireReadyQueueFence,
+  assertReadyQueueFence,
+  claimReadyQueueItem,
+  releaseReadyQueueFence,
+  renewReadyQueueFence,
+} from "./ready-queue-fence.mjs";
+
+const root = process.cwd();
+const lockPath = resolve(root, ".local/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();
+
+try {
+  const config = await readFile(resolve(root, ".agents/config/project.yaml"), "utf8");
+  if (!/^zaip:\s*\r?\n\s+enabled: true\s*$/m.test(config)) {
+    throw new Error("ZAIP must be enabled in this checkout");
+  }
+  let result;
+  if (action === "acquire" && args.length === 0) {
+    result = await acquireReadyQueueFence(lockPath, {
+      owner_token: randomUUID(),
+      now,
+      expires_at: expiry,
+    });
+  } else if (["claim", "renew", "assert", "release"].includes(action)) {
+    const [owner, rawFence, itemId] = args;
+    if (!owner || !/^[1-9]\d*$/.test(rawFence ?? "")) {
+      throw new Error("owner_token and positive fencing_token are required");
+    }
+    const lease = { owner_token: owner, fencing_token: Number(rawFence) };
+    if (action === "claim" && args.length === 3) {
+      result = await claimReadyQueueItem(lockPath, lease, itemId, now);
+    } else if (action === "renew" && args.length === 2) {
+      result = await renewReadyQueueFence(lockPath, lease, now, expiry);
+    } else if (action === "assert" && args.length === 2) {
+      result = await assertReadyQueueFence(lockPath, lease, now);
+    } else if (action === "release" && args.length === 2) {
+      result = await releaseReadyQueueFence(lockPath, lease, now);
+    } else {
+      throw new Error("Invalid ready-queue lease arguments");
+    }
+  } else {
+    throw new Error(
+      "Usage: ready-queue-lease.mjs acquire|claim OWNER FENCE ITEM|renew OWNER FENCE|assert OWNER FENCE|release OWNER FENCE",
+    );
+  }
+  process.stdout.write(`${JSON.stringify({ ok: result !== null && result !== false, result })}\n`);
+  if (result === null || result === false) process.exitCode = 2;
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

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

@@ -7,7 +7,7 @@ const root = resolve(import.meta.dirname, "../..");
 const read = (path) => readFile(resolve(root, path), "utf8");
 const repositoryReadme = resolve(root, "../../README.md");
 
-test("hourly ready queue contracts the native Codex scheduler and full ordered snapshot", async () => {
+test("hourly ready queue contracts the native Codex scheduler and one ordered item", async () => {
   const [installer, executor] = await Promise.all([
     read("zaip-skill-instalar-agendamento/SKILL.md"),
     read("zaip-skill-executar-fila-pronta/SKILL.md"),
@@ -35,7 +35,7 @@ test("hourly ready queue contracts the native Codex scheduler and full ordered s
   assert.match(installer, /standalone/);
   assert.match(installer, /sem duplicar/);
   assert.match(installer, /Nunca use o Agendador do Windows/);
-  assert.match(installer, /authorizes only canonically ready\/eligible items/);
+  assert.match(installer, /execute at most one top-level eligible item/);
   assert.match(installer, /a cada hora, no minuto 0/);
   assert.match(installer, /nova conversa/);
   assert.match(installer, /\.agents\/dashboard\/work-priority\.json/);
@@ -44,9 +44,12 @@ test("hourly ready queue contracts the native Codex scheduler and full ordered s
   assert.match(installer, /set_thread_title without threadId/);
   assert.match(installer, /\[YYYY-MM-DD-T-HH-mm\] Tarefa Agendada/);
 
-  assert.match(executor, /snapshot elegível/);
-  assert.match(executor, /todos os PRDs antes de SPECs, e todos os SPECs antes das Tasks/);
-  assert.match(executor, /descendem de PRD/);
+  assert.match(executor, /um único item superior/);
+  assert.match(executor, /zaip task ready-next --json/);
+  assert.match(executor, /somente o primeiro item superior elegível/);
+  assert.match(executor, /sem selecionar o próximo/);
+  assert.doesNotMatch(executor, /processe todos os PRDs/);
+  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/);
@@ -64,7 +67,7 @@ test("hourly ready queue contracts the native Codex scheduler and full ordered s
   assert.match(executor, /`prepared_plan` inline válido \*\*ou\*\* `plan_ref` válido, nunca ambos/);
   assert.match(executor, /não pode ter Execution vinculada/);
   assert.match(executor, /nunca pode ter sido iniciada ou tentada/);
-  assert.match(executor, /Para cada candidata/);
+  assert.match(executor, /Falha de leitura\/validação não é fila vazia/);
   assert.match(
     executor,
     /cujo próprio ID apareça em `task next` ou no conjunto materializado concorrente/,

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

@@ -71,7 +71,7 @@ Antes de encerrar com trabalho pendente ou responder a uma falha, aplique [conti
 
 ## Runtime gerenciado e compatibilidade
 
-1. Leia `execution.runtime`. Novo padrão `managed` despacha PRD/SPEC pelo provider, mantendo avulsas diretas. Ausente/manual preserva execução tradicional; `autonomous` também permite Task gerenciada explícita. Legados já tentados exigem `task migrate-autonomy` revisado; nenhum consumo é zerado.
+1. Leia `execution.runtime`. O padrão novo `codex_native` mantém o despacho no host Codex e exige subagentes nativos também para Task avulsa; `managed` é compatibilidade explícita de provider para PRD/SPEC, mantendo avulsas diretas nesse contrato legado. Ausente/manual preserva execução tradicional; `autonomous` também permite Task gerenciada explícita. Legados já tentados exigem `task migrate-autonomy` revisado; nenhum consumo é zerado.
 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.

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

@@ -7,8 +7,8 @@ Carregue antes de executar uma entrega ou delegar. Este contrato detalha o kerne
 - Para delegação Codex, Sub-Run ZAIP é somente subagente nativo de colaboração (`spawn_agent`). `create_thread` e `fork_thread` criam chats independentes e exigem pedido explícito do usuário; nunca são Sub-Run, fallback, retry ou prova de delegação. Se delegação nativa estiver indisponível, relate a limitação em vez de criar chat independente. Nome de catálogo, `task_name`, título ou prompt não prova ancestralidade nativa. Antes de repetir a mesma delegação limitada, aguarde ou reutilize seu filho pendente e capture somente ancestralidade/metadados observados em resultados nativos de spawn/terminal do host ou eventos SubagentStart/SubagentStop.
 - Cada `client_turn_id` observável tem uma Execution idempotente/claim atômico; sem ele use identidade local sem prometer idempotência. `interaction` read-only sem descendentes é conversa sem Task artificial e termina após a resposta entregue, sem executor ou finalizador; interaction com trabalho delegado e `delivery` exigem executor/finalizador. `delivery` é trabalho materializado e reuso exige kind/origem compatíveis. A raiz é `zaip-agent-orchestrator`; quando a barreira é exigida escolha executor por capacidade, permita reviewer/auditor/integrator e termine com `zaip-agent-finalizer` em `finalization`, após descendentes, bloqueando novas chamadas.
 - Hooks são best-effort: após cada spawn/terminal, o host autorizado a serviço do orquestrador executa `zaip subagent capture` idempotente com metadados reais. Na captura rica, preserve session/turn observados, `agent-id` com a identidade nativa retornada e `parent-agent-id`/`parent-run-id` do pai imediato exato; cada invocação preserva seu turn. Quando um evento terminal observado expõe somente agent_path, status, identidade catalogada e pai exato, `capture-terminal` aceita apenas `zaip-agent-finalizer` ou executor elegível para delivery com capacidade `task-delivery`; exige também `parent-run-id` igual ao `run_id` da raiz ativa exata, pois um client thread pode conter raízes concorrentes. O último segmento do agent_path deve ser seu `codex_task_name` canônico. O propósito deriva da identidade validada e session/turn/model/provider/usage permanecem indisponíveis; o fallback nunca substitui captura rica nem inventa modelo, effort, tokens ou custo.
-- Em `autonomy-v1`, carregue `RULE-AUTONOMY-DECISION`. Task avulsa preserva seleção manual do principal, evita subagentes e só delega por necessidade concreta; quando delegar, informe que modelo/esforço dos filhos seguem a política ZAIP, sem obrigação de herdar o principal. Fixe configuração por chamada e registre seleção efetivamente observada. Sem `autonomy`, preserve o contrato legado de `automatic_sources` (`spec`,`prd`).
-- Escaladas seguem o perfil congelado: Essencial nunca Astra automático; Equilibrado Sol/high, Astra/high, Astra/high, com execução Astra/high elegível no terceiro bloco; Persistente sem quota total. `RULE-ASTRA-DIAGNOSTIC` descreve também compatibilidade legada. Não use título/volume como prova nem alegue mudança de modelo apenas pelo prompt.
+- Em `autonomy-v1`, carregue `RULE-AUTONOMY-DECISION`. Conversation sem entrega responde diretamente; Task avulsa no padrão `codex_native` usa executor e Gui nativos. O principal preserva a seleção manual do host; cada filho segue a seleção ZAIP por papel/risco/fase, registrada conforme o modelo/esforço efetivamente observados. Capacidade ausente bloqueia a tentativa, nunca é substituída por prompt. Sem `autonomy`, preserve o contrato legado de `automatic_sources` (`spec`,`prd`).
+- Escaladas seguem o perfil congelado: Essencial nunca Astra automático; Equilibrado Sol/high, Sol/high, Astra/high, com execução Astra/high elegível no terceiro bloco; Persistente sem quota total. `RULE-ASTRA-DIAGNOSTIC` descreve também compatibilidade legada. Não use título/volume como prova nem alegue mudança de modelo apenas pelo prompt.
 - Todo PreparedPlan PRD/SPEC traz `model_signals` por Task; o framework persiste `model_profile`, `task-risk-v1` e motivos, usando `runtime_defaults`, `runtime`, política/defaults sem `standard` silencioso. Não infira fase/complexidade/transversalidade/ambiguidade/rework/custo/capacidade por contagem de arquivos; use sinais, fase/agente e capacidades. Cabeçalho e `model.selection.recorded` repetem a seleção enviada.
 - Plano visível: `DEFINE:`, `PLAN:`, `EXECUTE:` ou `VERIFY:`, 3–4 passos (máximo 5); omita fase sem ação e combine trivialidades.
 

package/templates/.agents/skills/zaip-skill-github-deploy/scripts/github-deploy-contract.test.mjs

@@ -57,22 +57,34 @@ test("deploy guidance preserves canonical Task identity and builder-versus-consu
   assert.ok(skill.includes("[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>"));
   assert.match(skill, /exclusively `CODEX` or `CLAUDE`; `AUTO` is not part/);
   assert.match(skill, /Consumer repositories follow their own GitHub-only policy/);
-  assert.match(skill, /“faça deploy” means the guarded push, GitHub Release and observation of the GitHub Actions npm publication/);
+  assert.match(
+    skill,
+    /“faça deploy” means the guarded push, GitHub Release and observation of the GitHub Actions npm publication/,
+  );
   assert.match(workflow, /commitar o diff evidenciado com pathspecs explícitos/);
 });
 
 test("framework deploy follows Release-triggered npm publication without claiming partial success", async () => {
-  const [skill, workflow, publishWorkflow] = await Promise.all([
+  const [skill, workflow, lock] = await Promise.all([
     readFile(resolve(skillRoot, "SKILL.md"), "utf8"),
     readFile(resolve(skillRoot, "references", "deployment-workflow.md"), "utf8"),
-    readFile(resolve(root, "..", ".github", "workflows", "publish-cli.yml"), "utf8"),
+    readFile(resolve(root, "config", "framework.lock.yaml"), "utf8"),
   ]);
-  assert.match(publishWorkflow, /release:\s*\n\s*types: \[published\]/);
-  assert.match(publishWorkflow, /npm publish /);
+  if (!lock.startsWith("# Generated transactionally by @zaip-ai/cli")) {
+    const publishWorkflow = await readFile(
+      resolve(root, "..", ".github", "workflows", "publish-cli.yml"),
+      "utf8",
+    );
+    assert.match(publishWorkflow, /release:\s*\n\s*types: \[published\]/);
+    assert.match(publishWorkflow, /npm publish /);
+  }
   assert.match(skill, /publish-cli\.yml.*registry confirmation/s);
   assert.match(skill, /npm fails or cannot be observed.*partial or blocked/);
   assert.match(skill, /explicit push-only request.*does not create a Release or publish npm/);
-  assert.match(workflow, /private Ed25519 release key is distinct from the Git SSH key and a local `\.env` npm token/);
+  assert.match(
+    workflow,
+    /private Ed25519 release key is distinct from the Git SSH key and a local `\.env` npm token/,
+  );
   assert.match(workflow, /A published Release with failed or unobserved npm is partial/);
 });
 

package/templates/.agents/skills/zaip-skill-instalar-agendamento/SKILL.md

@@ -8,10 +8,10 @@ description: Install or update the native Codex hourly scheduler for the ready-w
 Use esta skill somente quando a pessoa solicitar instalar, atualizar ou verificar o agendamento local da fila pronta. Ela configura o relógio; não inicia uma execução por conta própria.
 
 1. Confirme que o repositório é ZAIP habilitado e que a automação nativa de tarefas agendadas do Codex Desktop está chamável, com capacidade `automation_update`. Pare com `blocked` se ela não estiver disponível. Nunca use o Agendador do Windows, um arquivo, Git ou uma promessa de execução futura como substituto.
-2. Use `codex_app list_projects` para resolver o projeto Codex atual e seu checkout local real; não invente identificador, diretório ou contexto. Crie ou atualize, sem duplicar, a tarefa standalone de nome estável `ZAIP-AIOS - Fila Pronta Horária`: a cada hora, no minuto 0, em nova conversa no projeto resolvido. Ela abre uma única invocação com o prompt explícito `Ignore Automation memory and $CODEX_HOME. Start immediately by validating the repository and ready queue. First call codex_app set_thread_title without threadId, using America/Sao_Paulo local time in the exact format [YYYY-MM-DD-T-HH-mm] Tarefa Agendada; record a rename failure but continue the queue. Use $zaip-skill-executar-fila-pronta; this user-installed schedule authorizes only canonically ready/eligible items, never promotes draft or resumes blocked or failed work; respect the persisted manual order in .agents/dashboard/work-priority.json.`
+2. Use `codex_app list_projects` para resolver o projeto Codex atual e seu checkout local real; não invente identificador, diretório ou contexto. Crie ou atualize, sem duplicar, a tarefa standalone de nome estável `ZAIP-AIOS - Fila Pronta Horária`: a cada hora, no minuto 0, em nova conversa no projeto resolvido. Ela abre uma única invocação com o prompt explícito `Ignore Automation memory and $CODEX_HOME. Start immediately by validating the repository and ready queue. First call codex_app set_thread_title without threadId, using America/Sao_Paulo local time in the exact format [YYYY-MM-DD-T-HH-mm] Tarefa Agendada; record a rename failure but continue the queue. Use $zaip-skill-executar-fila-pronta; execute at most one top-level eligible item in this invocation, even if it finishes or becomes ineligible; never promote draft or resume blocked or failed work; respect the persisted manual order in .agents/dashboard/work-priority.json.`
 3. Antes de gravar, valide o checkout: raiz Git existente, `.agents/config/project.yaml` com `zaip.enabled: true`, runtime ZAIP disponível e caminho absoluto sem credenciais. Falhe fechado se algum requisito faltar; não registre uma tarefa parcial.
 4. Consulte `$CODEX_HOME/automations/*/automation.toml` somente em leitura, exclusivamente pelo nome estável para resolver identidade e deduplicação. É proibido criar, editar ou apagar TOML, ou usá-lo como fallback. Todas as visualizações e mutações da automação são exclusivamente por `codex_app automation_update`. Se houver mais de uma tarefa com esse nome, pare e reporte o conflito sem apagar nada. Se houver uma, inspecione seu ID, ação, agenda horária, nova conversa e diretório de trabalho e atualize-a; se não houver, crie uma. Preserve tarefas agendadas fora desse nome.
-5. Verifique após criar/atualizar que existe exatamente uma tarefa com o nome, agenda a cada hora no minuto 0, nova conversa, checkout esperado e prompt da skill executora que respeita `.agents/dashboard/work-priority.json`. Registre somente a evidência observada; não afirme que uma hora futura será executada.
+5. Verifique após criar/atualizar que existe exatamente uma tarefa com o nome, agenda a cada hora no minuto 0, nova conversa, checkout esperado e prompt da skill executora que respeita `.agents/dashboard/work-priority.json` e limita a rodada a um item superior. Registre somente a evidência observada; não afirme que uma hora futura será executada.
 6. Explique que o agendamento pertence à máquina e ao usuário que o instalou. O repositório versiona a skill e o contrato, mas não cria um relógio em clones, nem funciona com a máquina desligada, o Codex Desktop fechado ou sem a automação nativa.
 
 Não use esta skill para selecionar itens, burlar bloqueios, executar todos os itens `planned`, alterar prioridades do Kanban ou fazer deploy/push.

package/templates/.agents/skills/zaip-skill-release-qualification/SKILL.md

@@ -19,6 +19,12 @@ policy, gate definitions, runtime, channel, version, trusted key, expiry and art
 Consumer projects run their own policy commands through the distributed consumer helper, with
 their configured branch (default `beta`) and no framework npm requirements.
 The deployment skill must call the guarded helper, which prepares and verifies before sending.
+A framework signing key is resolved from the stable private directory
+`~/.codex/release-keys/zaip-aios/<trusted-key-id>/` unless explicit paths are supplied.
+Run `scripts/local-release-key.mjs preflight` before expensive gates; compare the local key
+and trust with GitHub when publishing. A missing or mismatched key fails closed. Do not
+silently generate a replacement, reuse a key ID for different key material, or remove the
+signature gate. See the local preparation guide for testing and controlled rotation.
 A changed candidate or invalid evidence requires new qualification.
 Full source qualification runs locally. Extended GitHub qualification is manual;
 the reduced publisher requires enrolled public trust and signed local qualification.

package/templates/.agents/skills/zaip-skill-release-qualification/references/local-preparation.md

@@ -4,6 +4,43 @@ Preparation does not authorize publication. Use guarded delivery only for an exp
 Store keys, trust stores, receipts and artifacts outside the repository. Commit and synchronize first;
 every gate is bound to the resulting clean SHA. Repair changes require a new candidate.
 
+The signing key ID is the trusted identity, not a filename. Resolve it with
+`gh variable get ZAIP_LOCAL_RELEASE_TRUSTED_KEY_ID --repo zaip-ai/zaip-aios`.
+By default, the private key lives at
+`~/.codex/release-keys/zaip-aios/<key-id>/release-private.pem` and its local
+trust store at `~/.codex/release-keys/zaip-aios/<key-id>/trust/` on the current
+machine. This location is shared by the machine's worktrees but never by Git.
+Keep a secure backup and restrict OS access; Git ignore alone does not protect a
+private key. `.local/` may hold a pointer or disposable test evidence, but must not
+be the only copy of a production signing key.
+
+Run `node scripts/local-release-key.mjs preflight --key-id <trusted-key-id> --channel latest --github-repo zaip-ai/zaip-aios` before the expensive release
+gates. It checks the private/public pair, local trust and the GitHub public key
+without printing key material. Omit `--github-repo` to test completely offline.
+`prepare` and `local-release-deploy` resolve the stable paths automatically;
+`--private-key` and `--trust-store` remain explicit overrides. Missing/mismatched
+material blocks before qualification. Never auto-create a signing key during deploy.
+
+For a local-only proof, generate an ephemeral Ed25519 pair outside the repository,
+bootstrap a temporary trust store, then run `preflight` without `--github-repo` and
+the release helper with `--dry-run --offline-dry-run`, explicit temporary
+key/trust paths and an exact
+clean candidate. The receipt must verify against that temporary trust store; this
+does **not** authorize production publication or claim GitHub trust.
+
+If the production private key is genuinely unavailable, rotate only with explicit
+authorization. Use a **new** key ID and a new stable directory; never create a new
+pair under the old ID or overwrite an existing key. Bootstrap the new local trust,
+run offline preflight, then run
+`node scripts/local-release-key.mjs rotate --confirm-rotate --github-repo zaip-ai/zaip-aios --expected-old-key-id <old-id> --new-key-id <new-id> --public-key <new-public.pem> --backup-dir <new-external-backup-directory>`.
+The rotation saves the old public trust for rollback, updates only the trusted
+public key and ID, verifies readback, and attempts rollback on error. It does not
+alter the policy, publish a Release, or touch npm credentials. Do not rotate
+while a release publisher is running. Verify the resulting `preflight` with
+`--github-repo` before the next candidate qualification. Protect and separately
+back up the private key; the trust backup contains only public material. Restoring
+the old public trust alone cannot resume signing when the old private key is lost.
+
 ## Framework repository: main and GitHub Actions npm
 
 These commands exist only in the source repository `zaip-ai/zaip-aios`. Values in angle brackets
@@ -11,15 +48,20 @@ must be replaced with the authorized candidate and external paths. GitHub versio
 to tag `vN.N` and package version `N.N.0`.
 
 ```text
-node scripts/local-release-preparation.mjs keygen --output-dir <new-key-directory>
-node scripts/local-release-preparation.mjs bootstrap --trust-store <trust-directory> --public-key <public-key.pem> --key-id maintainer --channels latest
-node scripts/local-release-preparation.mjs prepare --repository <absolute-repository> --expected-repository zaip-ai/zaip-aios --sha <40-character-sha> --output-dir <candidate-artifacts> --policy <policy.json> --private-key <private-key.pem> --key-id maintainer --channel latest --version <N.N> --expires-at <future-ISO-within-seven-days> --trust-store <trust-directory> --profile essential
+node scripts/local-release-preparation.mjs keygen --output-dir <new-stable-private-key-directory>
+node scripts/local-release-preparation.mjs bootstrap --trust-store <new-stable-private-key-directory>/trust --public-key <new-stable-private-key-directory>/release-public.pem --key-id <new-key-id> --channels latest
+node scripts/local-release-key.mjs preflight --key-id <new-key-id> --channel latest
+node scripts/local-release-preparation.mjs prepare --repository <absolute-repository> --expected-repository zaip-ai/zaip-aios --sha <40-character-sha> --output-dir <candidate-artifacts> --policy <policy.json> --key-id <trusted-key-id> --channel latest --version <N.N> --expires-at <future-ISO-within-seven-days> --profile essential
 ```
 
 The framework policy is an administrator-reviewed file whose bytes must match the protected
 GitHub policy before Release publication. The user's 2026-09-23 authorization permits the
 builder deploy to update only `ZAIP_LOCAL_RELEASE_POLICY_B64` for each exact new version after
 successful signed local qualification, with byte-for-byte readback and no key/trust rotation.
+The user separately authorized a one-time trust rotation on 2026-09-25 after the
+`maintainer-v3` private key could not be located. The active trust ID is now
+`maintainer-v4`; the old public trust is backed up outside the repository for
+rollback. This does not authorize future rotations without an explicit request.
 The policy must name the exact repository, `main`, channel, `N.N`/`N.N.0` versions, selected
 fixed qualification profile, `github-actions-only`, `signed-release-linux-smoke`, and disabled
 force/replacement/pilot flags. Do not reuse an older version's policy unchanged or ask again
@@ -28,7 +70,7 @@ fails at the first failed gate. The default `essential-v3` profile validates sou
 build/type integrity, package/SBOM/TGZ binding, dependency audit and one clean installed-consumer
 doctor/SQLite/API smoke. It does not run browser navigation across every dashboard tab or XLSX
 exports. `--profile full` explicitly selects `full-v2`, which also runs the full source suite,
-browser and XLSX qualification. Essential preparation has a 15-minute deadline; full preparation
+browser and XLSX qualification. Essential preparation has a 30-minute deadline; full preparation
 has a 60-minute deadline. Both use process-tree
 termination and cleanup after expiry. A failure never produces a successful receipt. Receipts bind
 the selected profile and its fixed gate list, so former receipts require requalification.
@@ -48,7 +90,7 @@ is refused. Choose a new output path after repair instead of deleting or overwri
 For an authorized release, call this command with the same arguments and paths:
 
 ```text
-node scripts/local-release-deploy.mjs --repository <absolute-repository> --expected-repository zaip-ai/zaip-aios --sha <40-character-sha> --branch main --output-dir <candidate-artifacts> --policy <policy.json> --private-key <private-key.pem> --key-id maintainer --channel latest --version <N.N> --expires-at <future-ISO-within-seven-days> --trust-store <trust-directory> --notes-file <reviewed-notes.md> --inventory-file <release-inventory.json> --from <previous-release-tag> --profile essential
+node scripts/local-release-deploy.mjs --repository <absolute-repository> --expected-repository zaip-ai/zaip-aios --sha <40-character-sha> --branch main --output-dir <candidate-artifacts> --policy <policy.json> --key-id <trusted-key-id> --channel latest --version <N.N> --expires-at <future-ISO-within-seven-days> --notes-file <reviewed-notes.md> --inventory-file <release-inventory.json> --from <previous-release-tag> --profile essential
 ```
 
 `--dry-run` prepares and verifies without sending. The live command verifies again around