@zaip-ai/cli 4.8.0 → 5.0.0

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

@@ -29,6 +29,31 @@ const input = (request, identity = consumer, policy = DEFAULT_POLICY) => ({
   policy,
 });
 
+test("literal SPEC continuation binds only its explicit version and optional release suffix", () => {
+  const base =
+    "pode retomar a execução da SPEC até finalizar todas as tasks e fazer publicação deploy da v5.0";
+  for (const request of [base, `${base} com release`, `${base} com release e npm publicado`]) {
+    const plan = resolveDeployment(input(request, builder));
+    assert.equal(plan.mode, "release", request);
+    assert.equal(plan.phase, "publish", request);
+    assert.equal(plan.scope, "current-work", request);
+    assert.equal(plan.version, "5.0", request);
+    assert.equal(plan.npm_publication, true, request);
+  }
+  assert.equal(resolveDeployment(input(base.replace("v5.0", "v6.2"), builder)).version, "6.2");
+  for (const request of [
+    `"${base}"`,
+    `o usuário disse '${base}'`,
+    `${base}?`,
+    `${base} se eu confirmar`,
+    `${base} não publique`,
+    `${base} e faça outra coisa`,
+    `${base} com npm publicado`,
+    base.replace("v5.0", "v05.0"),
+  ])
+    assert.equal(resolveDeployment(input(request, builder)).mode, "none", request);
+});
+
 test("fixed defaults, explicit intent and preparation: Portuguese/English decision matrix", () => {
   const cases = [
     ["faça deploy", null, "publish"],
@@ -127,6 +152,28 @@ test("final adjustments with an explicit publication goal preserve the actual hu
   assert.equal(prepare.phase, "prepare");
   assert.equal(prepare.npm_publication, false);
 });
+test("short positive publication statements bind their stated version without promoting questions or conditions", () => {
+  const request = "Boa, boa. Eu quero publicar quatro ponto nove, sim";
+  for (const [utterance, version] of [
+    [request, "4.9"],
+    ["Eu quero publicar quatro ponto oito, sim", "4.8"],
+    ["Quero publicar a versão v5.0", "5.0"],
+  ]) {
+    const plan = resolveDeployment(input(utterance, builder));
+    assert.equal(plan.mode, "release", utterance);
+    assert.equal(plan.phase, "publish", utterance);
+    assert.equal(plan.scope, "current-work", utterance);
+    assert.equal(plan.version, version, utterance);
+  }
+  for (const unsafe of [
+    `${request}?`,
+    "Boa, boa. Eu não quero publicar quatro ponto nove, sim",
+    `Se estiver pronto, ${request}`,
+    `O usuário disse '${request}'`,
+    "Eu quero publicar quatro ponto nove se vocês aprovarem",
+  ])
+    assert.equal(resolveDeployment(input(unsafe, builder)).mode, "none", unsafe);
+});
 test("preferences are project-owned; one-shot overrides, scope and invalid config are explicit", () => {
   const preference = { ...DEFAULT_POLICY, default_mode: "release" };
   assert.equal(resolveDeployment(input("faça deploy", consumer, preference)).mode, "release");
@@ -220,19 +267,21 @@ test("commits route checks before push, sends the exact SHA and never creates re
   assert.equal((await guardedCommits({ ...value, dryRun: true }, operations)).pushed, false);
   assert.ok(!events.includes("preflight"));
 });
-test("critical builder commit qualifies locally and waits for exact main CI", async () => {
+test("critical builder commit uses portable injected gates and fails closed if either is missing", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-critical-portable-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
   const current = input("faça deploy apenas commits", builder);
   const sha = "a".repeat(40);
   const events = [];
   const value = {
-    repository: process.cwd(),
+    repository: root,
     request: current.request,
     plan: resolveDeployment(current),
     sha,
     branch: "main",
     checks: [{ command: "node", args: ["--test", "fixture.test.mjs"] }],
   };
-  await guardedCommits(value, {
+  const operations = {
     readInput: async () => current,
     identity: () => {},
     branchFor: async () => "main",
@@ -243,8 +292,17 @@ test("critical builder commit qualifies locally and waits for exact main CI", as
     push: async () => events.push("main"),
     remoteSha: async () => sha,
     verifyMainCi: async () => events.push("main-ci"),
-  });
+  };
+  await guardedCommits(value, operations);
   assert.deepEqual(events, ["checks", "preflight", "qualify", "main", "main-ci"]);
+  for (const missing of ["qualifyPreMain", "verifyMainCi"]) {
+    events.length = 0;
+    await assert.rejects(
+      guardedCommits(value, { ...operations, [missing]: undefined }),
+      /remote-candidate-gate\.mjs/,
+    );
+    assert.ok(!events.includes("main"), `${missing} must fail before push`);
+  }
 });
 test("critical Task in an earlier candidate commit requires candidate-bound proof", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "zaip-critical-range-"));

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

@@ -67,10 +67,7 @@ test("deploy guidance preserves canonical Task identity and builder-versus-consu
     skill,
     /verified builder means Release plus npm through Actions; a consumer means commits plus push/,
   );
-  assert.match(
-    workflow,
-    /Preserve trabalho\/index concorrentes e causalidade de todos os commits publicados/,
-  );
+  assert.match(workflow, /Preserve trabalho, index, causalidade, SHA, integridade e autorização/);
 });
 
 test("framework deploy follows Release-triggered npm publication without claiming partial success", async () => {
@@ -124,10 +121,15 @@ test("deploy permission and reconciliation remain explicit and recoverable", asy
 });
 
 test("workflow retains the explicit publication routing contract", async () => {
-  const workflow = await readFile(resolve(root, "rules", "workflow.md"), "utf8");
+  const [workflow, core, skill] = await Promise.all([
+    readFile(resolve(root, "rules", "workflow.md"), "utf8"),
+    readFile(resolve(root, "rules", "core.md"), "utf8"),
+    readFile(resolve(skillRoot, "SKILL.md"), "utf8"),
+  ]);
   assert.match(workflow, /\$zaip-skill-github-deploy/);
   assert.match(workflow, /deploy-policy\.json/);
-  assert.match(workflow, /current-work/);
+  assert.match(core, /Escopo `current-work`/);
+  assert.match(skill, /Default scope is `current-work`/);
 });
 
 test("release guidance requires reviewed categorized notes and published-body readback", async () => {

package/templates/.agents/skills/zaip-skill-github-deploy/scripts/guarded-commits.mjs

@@ -134,9 +134,11 @@ export async function guardedCommits(input, operations = {}) {
       input.sha,
       input.remote ?? "origin",
     ));
-  const candidateGate = critical
-    ? await import(pathToFileURL(resolve(root, "scripts/remote-candidate-gate.mjs")).href)
-    : null;
+  // Portable callers can supply both gates; otherwise load the real gate before push.
+  const candidateGate =
+    critical && (!operations.qualifyPreMain || !operations.verifyMainCi)
+      ? await import(pathToFileURL(resolve(root, "scripts/remote-candidate-gate.mjs")).href)
+      : null;
   if (critical) {
     await (operations.qualifyPreMain ?? candidateGate.qualifyLocalCandidate)({
       repository: root,

package/templates/.agents/skills/zaip-skill-lifecycle-closure/SKILL.md

@@ -42,6 +42,13 @@ the supplied ID and canonical record; never scan ordinary history to guess a tar
    while the responsible root is active. A finalizer stop may close that root, so do not
    send it an unfinished framework lock, failed local check, or outdated SHA evidence.
    Rebind validation and independent review after each candidate-changing commit.
+10. For a confirmed residual Git `index.lock`, use the official `git-lock recover --task TASK
+    --run RUN --decision DEC-HUMAN-ID --json` command before claiming a Task workspace.
+    The Decision must explicitly authorize this lock recovery. The command verifies the real
+    Git dir (including linked worktrees), a regular empty lock older than ten minutes,
+    no active Git process or operation marker, and a stable second stat; it moves the lock
+    to a verified backup. An inconclusive check refuses recovery. Preserve that backup
+    and report its path; use the existing Task workspace flow afterwards.
 
 Use `$zaip-skill-reconcile-telemetry` only for missing observed usage after lifecycle
 identity is correct; it is not a substitute for closure.

package/templates/.agents/skills/zaip-skill-maintenance-enter/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: zaip-skill-maintenance-enter
+description: Enter explicitly authorized ZAIP framework maintenance with governance disabled and canonical telemetry enabled.
+---
+
+# Entrar em manutenção
+
+Use quando o usuário pedir manutenção direta do framework ou autorizar desligar sua governança para uma correção delimitada. Um bloqueio de ferramenta, sozinho, não autoriza manutenção. Reutilize a autorização vigente; não peça outra confirmação para o mesmo escopo.
+
+1. No agente principal, confirme a raiz e o escopo autorizado. O toggle afeta todos os agentes e chats deste projeto: não entre enquanto houver trabalho governado concorrente sem coordenação. Um subagente solicita a transição ao principal; não a executa por conta própria.
+2. Execute na raiz, com o Node disponível no host:
+
+   ```text
+   node .agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.mjs enter
+   ```
+
+   Para outra raiz explícita, acrescente `--root <diretório>`. Use hooks atualizados com os dois controles independentes. A leitura estática do script detecta a presença da interface; não atesta integridade, habilitação no cliente ou coleta real. A confirmação vem da etapa 4. Usa o [parser YAML distribuído](../zaip-skill-github-deploy/scripts/yaml-parser.mjs); não requer instalação de dependências. Os controles devem estar no formato canônico de blocos YAML com chaves sem aspas e booleanos literais; formatos alternativos são recusados sem alteração.
+3. Confira a saída JSON: `zaip_enabled: false`, `tracking_enabled: true`. A entrada liga tracking caso estivesse desligado; isso faz parte deste modo com telemetria. Somente os dois booleanos mudam; comentários e demais configurações ficam preservados. Repetir a entrada é idempotente. O recibo de recuperação fica em `.local/zaip-maintenance/state.json`.
+4. Faça uma chamada real de leitura e confira o registro observado em `.local/hooks/observations`. Os quatro hooks permanecem instalados e habilitados no cliente; não altere `.codex/config.toml`. O script não liga um hook desabilitado na interface. Configuração ligada não prova captura: confira o recibo e o processamento canônico sem inventar IDs ou métricas. Se o cliente não disparar o hook, informe a pendência; não declare telemetria comprovada.
+5. Trabalhe diretamente com as ferramentas nativas do Codex no escopo autorizado, sem materializar Task/SPEC/PRD, claims ou transições ZAIP apenas para satisfazer sua governança suspensa. Preserve registros existentes. A manutenção não amplia permissões do host, acesso a segredos, publicação ou ações destrutivas. Nunca reinicie, desligue, suspenda, hiberne ou encerre a sessão do computador.
+6. Ao terminar a manutenção, execute `$zaip-skill-maintenance-exit`, salvo pedido explícito para permanecer neste modo. Ao retomar após interrupção, use o comando com `status`, leia o estado atual e prossiga; não restaure uma cópia inteira de `project.yaml` sobre edições feitas durante a manutenção.
+
+O recibo local registra apenas a transição, não substitui a telemetria. Os hooks existentes continuam observando a sessão e salvando dados canônicos conforme `tracking.storage_mode`; valores indisponíveis continuam nulos. Encerrar manutenção não encerra automaticamente Tasks ou Runs históricas.

package/templates/.agents/skills/zaip-skill-maintenance-enter/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Entrar em manutenção"
+  short_description: "Desativa a governança e mantém a telemetria"
+  default_prompt: "Use $zaip-skill-maintenance-enter para entrar em manutenção com telemetria ativa."

package/templates/.agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.mjs

@@ -0,0 +1,213 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseDocument } from "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs";
+
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+
+function physical(root, parts, create = false) {
+  let current = root;
+  for (const part of parts) {
+    current = resolve(current, part);
+    if (create && !existsSync(current)) mkdirSync(current);
+    if (lstatSync(current).isSymbolicLink()) throw Error(`Linked maintenance path: ${current}`);
+  }
+  return current;
+}
+
+function atomic(path, content, expected) {
+  if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw Error("Linked output rejected");
+  const temporary = resolve(dirname(path), `.maintenance-${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, content, {
+      flag: "wx",
+      mode: existsSync(path) ? lstatSync(path).mode & 0o777 : 0o600,
+    });
+    if (expected !== undefined && readFileSync(path, "utf8") !== expected)
+      throw Error("Configuration changed concurrently; retry after coordinating writers");
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function inspect(source) {
+  if (Buffer.byteLength(source) > 65536) throw Error("Project policy exceeds the hook input limit");
+  const doc = parseDocument(source, { strict: true, uniqueKeys: true });
+  if (doc.errors.length || doc.warnings.length) throw Error("Invalid or unsupported project YAML");
+  // Accept the canonical block form only. Do not execute JavaScript from --root.
+  for (const name of ["zaip", "tracking"]) {
+    const pair = doc.contents?.items?.find((item) => item.key?.value === name);
+    const section = pair?.value;
+    const enabled = section?.items?.find((item) => item.key?.value === "enabled");
+    const key = pair?.key;
+    if (
+      !key?.range ||
+      !enabled?.key?.range ||
+      section.flow ||
+      section.anchor ||
+      section.tag ||
+      source.slice(key.range[0], key.range[1]) !== name ||
+      (key.range[0] > 0 && source[key.range[0] - 1] !== "\n") ||
+      !new RegExp("^" + name + ":[ \\t]*(?:#[^\\r\\n]*)?\\r?\\n").test(
+        source.slice(key.range[0]),
+      ) ||
+      source.slice(enabled.key.range[0], enabled.key.range[1]) !== "enabled"
+    ) {
+      throw Error("Use canonical unquoted zaip/tracking blocks with literal enabled keys");
+    }
+    const lineStart = source.lastIndexOf("\n", enabled.key.range[0] - 1) + 1;
+    if (
+      !/^ +$/.test(source.slice(lineStart, enabled.key.range[0])) ||
+      !enabled.value?.range ||
+      !/^: +$/.test(source.slice(enabled.key.range[1], enabled.value.range[0]))
+    ) {
+      throw Error("Use canonical enabled: true/false on one indented line");
+    }
+  }
+  const nodes = ["zaip", "tracking"].map((key) => doc.getIn([key, "enabled"], true));
+  for (const node of nodes) {
+    if (
+      !node ||
+      typeof node.value !== "boolean" ||
+      node.anchor ||
+      node.tag ||
+      !node.range ||
+      !/^(true|false)$/.test(source.slice(node.range[0], node.range[1]))
+    ) {
+      throw Error("zaip.enabled and tracking.enabled must be explicit literal booleans");
+    }
+  }
+  const policy = { governance: nodes[0].value, tracking: nodes[1].value };
+  return { nodes, policy };
+}
+
+export async function maintenance(action, directory = process.cwd()) {
+  if (!["enter", "exit", "status"].includes(action))
+    throw Error("Use enter, exit or status [--root <directory>]");
+  const root = realpathSync(resolve(directory));
+  const config = physical(root, [".agents", "config", "project.yaml"]);
+  const hook = physical(root, [".codex", "hooks", "zaip-hook-activation.mjs"]);
+  const hookSource = readFileSync(hook, "utf8");
+  if (
+    !hookSource.includes("export function parseHookPolicies(") ||
+    !hookSource.includes("export async function hookPolicies(")
+  )
+    throw Error(
+      "Update the four hooks to support independent governance and tracking before maintenance",
+    );
+  let source = readFileSync(config, "utf8");
+  let parsed = inspect(source);
+  const result = (state, changed) => ({
+    action,
+    root,
+    zaip_enabled: parsed.policy.governance,
+    tracking_enabled: parsed.policy.tracking,
+    phase: state?.phase ?? null,
+    changed,
+    config_sha256: hash(source),
+    telemetry: "verify_native_hook_observation",
+    hook_check: "interface_presence_only",
+  });
+  if (action === "status") {
+    const path = resolve(root, ".local/zaip-maintenance/state.json");
+    if (!existsSync(path)) return result(null, false);
+    physical(root, [".local", "zaip-maintenance", "state.json"]);
+    const state = JSON.parse(readFileSync(path, "utf8"));
+    if (state.schema_version !== 1 || state.root !== root)
+      throw Error("Invalid maintenance receipt");
+    return result(state, false);
+  }
+  const local = physical(root, [".local", "zaip-maintenance"], true);
+  const lock = resolve(local, "transition.lock");
+  let fd;
+  try {
+    fd = openSync(lock, "wx", 0o600);
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw Error(
+        "Maintenance transition locked; inspect transition.lock and coordinate its owner",
+      );
+    throw error;
+  }
+  try {
+    writeFileSync(fd, JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() }));
+    source = readFileSync(config, "utf8");
+    parsed = inspect(source);
+    const statePath = resolve(local, "state.json");
+    let state = null;
+    if (existsSync(statePath)) {
+      physical(root, [".local", "zaip-maintenance", "state.json"]);
+      state = JSON.parse(readFileSync(statePath, "utf8"));
+      if (state.schema_version !== 1 || state.root !== root)
+        throw Error("Invalid maintenance receipt");
+    }
+    const desired = action === "exit";
+    const phase = desired ? "inactive" : "active";
+    if (state?.phase === phase && parsed.policy.governance === desired && parsed.policy.tracking)
+      return result(state, false);
+    if (!state || (action === "enter" && state.phase === "inactive")) {
+      state = {
+        schema_version: 1,
+        root,
+        started_at: new Date().toISOString(),
+        previous: {
+          zaip_enabled: parsed.policy.governance,
+          tracking_enabled: parsed.policy.tracking,
+        },
+        initial_config_sha256: hash(source),
+      };
+    }
+    state.phase = desired ? "exiting" : "entering";
+    atomic(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    let next = source;
+    const replacements = parsed.nodes
+      .map((node, index) => ({
+        start: node.range[0],
+        end: node.range[1],
+        value: String(index === 0 ? desired : true),
+      }))
+      .sort((a, b) => b.start - a.start);
+    for (const edit of replacements)
+      next = next.slice(0, edit.start) + edit.value + next.slice(edit.end);
+    inspect(next);
+    const changed = next !== source;
+    if (changed) atomic(config, next, source);
+    source = readFileSync(config, "utf8");
+    parsed = inspect(source);
+    if (parsed.policy.governance !== desired || !parsed.policy.tracking)
+      throw Error("Transition verification failed");
+    state.phase = phase;
+    state.updated_at = new Date().toISOString();
+    state.config_sha256 = hash(source);
+    atomic(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    return result(state, changed);
+  } finally {
+    closeSync(fd);
+    unlinkSync(lock);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const [action, flag, directory, ...extra] = process.argv.slice(2);
+  try {
+    if (extra.length || (flag !== undefined && (flag !== "--root" || !directory)))
+      throw Error("Use enter, exit or status [--root <directory>]");
+    console.log(JSON.stringify(await maintenance(action, directory)));
+  } catch (error) {
+    console.error(`Maintenance transition failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/templates/.agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.test.mjs

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { test } from "node:test";
+import { maintenance } from "./maintenance.mjs";
+
+const sourceRoot = resolve(import.meta.dirname, "../../../..");
+// Public-template tests use the installed hook contract from the builder workspace.
+const hookRoot = existsSync(resolve(sourceRoot, ".codex/hooks/zaip-hook-activation.mjs"))
+  ? sourceRoot
+  : resolve(sourceRoot, "../../../..");
+const original =
+  "# preserved\r\nzaip:\r\n  enabled: true # governance\r\ntracking:\r\n  enabled: true\r\n  storage_mode: tracked_sanitized\r\nproject:\r\n  name: original\r\n";
+function fixture(t, source = original) {
+  const root = mkdtempSync(resolve(tmpdir(), "zaip-maintenance-test-"));
+  t.after(() => rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }));
+  mkdirSync(resolve(root, ".agents/config"), { recursive: true });
+  mkdirSync(resolve(root, ".codex/hooks"), { recursive: true });
+  const config = resolve(root, ".agents/config/project.yaml");
+  writeFileSync(config, source);
+  copyFileSync(
+    resolve(hookRoot, ".codex/hooks/zaip-hook-activation.mjs"),
+    resolve(root, ".codex/hooks/zaip-hook-activation.mjs"),
+  );
+  return {
+    root,
+    config,
+    read: () => readFileSync(config, "utf8"),
+    state: resolve(root, ".local/zaip-maintenance/state.json"),
+  };
+}
+
+test("enter and exit retain telemetry, comments and CRLF; repetition is idempotent", async (t) => {
+  const f = fixture(t);
+  const entered = await maintenance("enter", f.root);
+  assert.equal(entered.zaip_enabled, false);
+  assert.equal(entered.tracking_enabled, true);
+  assert.equal(
+    f.read(),
+    original.replace("enabled: true # governance", "enabled: false # governance"),
+  );
+  const state = readFileSync(f.state, "utf8");
+  assert.equal((await maintenance("status", f.root)).phase, "active");
+  assert.equal((await maintenance("enter", f.root)).changed, false);
+  assert.equal(readFileSync(f.state, "utf8"), state);
+  assert.equal((await maintenance("exit", f.root)).zaip_enabled, true);
+  assert.equal(f.read(), original);
+  assert.equal((await maintenance("exit", f.root)).changed, false);
+});
+
+test("exit preserves configuration edits made during maintenance", async (t) => {
+  const f = fixture(t);
+  await maintenance("enter", f.root);
+  writeFileSync(f.config, f.read().replace("name: original", "name: changed"));
+  await maintenance("exit", f.root);
+  assert.equal(f.read(), original.replace("name: original", "name: changed"));
+});
+
+test("manual disabled state and disabled tracking become active telemetry and exit restores governance", async (t) => {
+  const f = fixture(t, original.replaceAll("enabled: true", "enabled: false"));
+  const entered = await maintenance("enter", f.root);
+  assert.equal(entered.zaip_enabled, false);
+  assert.equal(entered.tracking_enabled, true);
+  assert.equal((await maintenance("exit", f.root)).zaip_enabled, true);
+  assert.equal(f.read(), original);
+});
+
+test("exit without a prior receipt supports manual maintenance", async (t) => {
+  const f = fixture(
+    t,
+    original.replace("enabled: true # governance", "enabled: false # governance"),
+  );
+  assert.equal((await maintenance("exit", f.root)).tracking_enabled, true);
+  assert.equal(f.read(), original);
+});
+
+test("status never changes configuration or creates local state", async (t) => {
+  const f = fixture(t);
+  assert.equal((await maintenance("status", f.root)).zaip_enabled, true);
+  assert.equal(existsSync(resolve(f.root, ".local")), false);
+  assert.equal(f.read(), original);
+});
+
+test("never executes hook code supplied by the target directory", async (t) => {
+  const f = fixture(t);
+  writeFileSync(
+    resolve(f.root, ".codex/hooks/zaip-hook-activation.mjs"),
+    'throw Error("Target code must not execute");\nexport function parseHookPolicies() {}\nexport async function hookPolicies() {}\n',
+  );
+  assert.equal((await maintenance("status", f.root)).zaip_enabled, true);
+  assert.equal((await maintenance("enter", f.root)).tracking_enabled, true);
+  assert.equal((await maintenance("exit", f.root)).zaip_enabled, true);
+});
+
+for (const [label, source] of [
+  ["string boolean", original.replace("enabled: true # governance", 'enabled: "true"')],
+  ["duplicate control", original.replace("zaip:", "zaip:\n  enabled: false")],
+  ["missing tracking", "zaip:\n  enabled: true\n"],
+  ["malformed YAML", `${original}broken: [\n`],
+  ["alias control", original.replace("enabled: true # governance", "enabled: &flag true")],
+  ["hook-incompatible key", original.replace("zaip:", '"zaip":')],
+  ["explicit enabled key", original.replace("enabled: true # governance", "? enabled\r\n  : true")],
+  ["space before colon", original.replace("enabled: true # governance", "enabled : true")],
+]) {
+  test(`rejects ${label} before mutation`, async (t) => {
+    const f = fixture(t, source);
+    await assert.rejects(maintenance("enter", f.root));
+    assert.equal(f.read(), source);
+    assert.equal(existsSync(resolve(f.root, ".local")), false);
+  });
+}
+
+test("contention refuses a second transition without touching the owner lock", async (t) => {
+  const f = fixture(t);
+  const dir = resolve(f.root, ".local/zaip-maintenance");
+  mkdirSync(dir, { recursive: true });
+  const lock = resolve(dir, "transition.lock");
+  writeFileSync(lock, "existing owner");
+  await assert.rejects(maintenance("enter", f.root), /locked/);
+  assert.equal(readFileSync(lock, "utf8"), "existing owner");
+  assert.equal(f.read(), original);
+});
+
+test("interrupted receipt can be reconciled without resetting the original snapshot", async (t) => {
+  const f = fixture(t);
+  await maintenance("enter", f.root);
+  const state = JSON.parse(readFileSync(f.state, "utf8"));
+  state.phase = "entering";
+  writeFileSync(f.state, JSON.stringify(state));
+  assert.equal((await maintenance("enter", f.root)).changed, false);
+  assert.equal(
+    JSON.parse(readFileSync(f.state, "utf8")).initial_config_sha256,
+    state.initial_config_sha256,
+  );
+  assert.equal((await maintenance("exit", f.root)).zaip_enabled, true);
+});
+
+test("linked configuration directories cannot mutate another project", async (t) => {
+  const target = fixture(t);
+  const f = fixture(t);
+  rmSync(resolve(f.root, ".agents/config"), { recursive: true });
+  symlinkSync(
+    resolve(target.root, ".agents/config"),
+    resolve(f.root, ".agents/config"),
+    "junction",
+  );
+  t.after(() => {
+    if (existsSync(resolve(f.root, ".agents/config"))) rmSync(resolve(f.root, ".agents/config"));
+  });
+  await assert.rejects(maintenance("enter", f.root), /Linked/);
+  assert.equal(target.read(), original);
+});
+
+test("CLI works from another cwd with an explicit root and rejects extra arguments", (t) => {
+  const f = fixture(t);
+  const script = resolve(import.meta.dirname, "maintenance.mjs");
+  const run = (...args) =>
+    spawnSync(process.execPath, [script, ...args], {
+      cwd: tmpdir(),
+      encoding: "utf8",
+      windowsHide: true,
+    });
+  const entered = run("enter", "--root", f.root);
+  assert.equal(entered.status, 0, entered.stderr);
+  assert.equal(JSON.parse(entered.stdout).tracking_enabled, true);
+  const before = f.read();
+  assert.equal(run("exit", "--root", f.root, "extra").status, 1);
+  assert.equal(f.read(), before);
+  assert.equal(run("exit", "--root", f.root).status, 0);
+});
+
+test("installed helper runs without node_modules or the builder checkout", (t) => {
+  const f = fixture(t);
+  const script = resolve(
+    f.root,
+    ".agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.mjs",
+  );
+  const parser = resolve(f.root, ".agents/skills/zaip-skill-github-deploy/scripts/yaml-parser.mjs");
+  mkdirSync(resolve(script, ".."), { recursive: true });
+  mkdirSync(resolve(parser, ".."), { recursive: true });
+  copyFileSync(resolve(import.meta.dirname, "maintenance.mjs"), script);
+  copyFileSync(
+    resolve(import.meta.dirname, "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs"),
+    parser,
+  );
+  for (const action of ["enter", "exit"]) {
+    const result = spawnSync(process.execPath, [script, action], {
+      cwd: f.root,
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(JSON.parse(result.stdout).tracking_enabled, true);
+  }
+  assert.equal(f.read(), original);
+});

package/templates/.agents/skills/zaip-skill-maintenance-exit/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: zaip-skill-maintenance-exit
+description: Finish authorized ZAIP maintenance by reactivating governance, retaining telemetry, and verifying the next native hook invocation.
+---
+
+# Sair da manutenção
+
+Use ao concluir manutenção autorizada ou quando o usuário pedir reativação. Funciona também após desativação manual sem recibo prévio. No agente principal, termine ou coordene os escritores de manutenção antes de reativar a governança compartilhada do projeto.
+
+1. Execute na raiz, com o Node do host:
+
+   ```text
+   node .agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.mjs exit
+   ```
+
+   O [script compartilhado](../zaip-skill-maintenance-enter/scripts/maintenance.mjs) também aceita `status` e `--root <diretório>`. Depende da skill de entrada e do parser YAML distribuído; não exige Node instalado no projeto.
+2. Exija `zaip_enabled: true` e `tracking_enabled: true` na saída. A saída reativa ZAIP mesmo quando ele já estava desligado antes da entrada, e mantém tracking ligado. Ela altera somente esses booleanos no arquivo atual: preserva edições de configuração feitas durante a manutenção. Não restaure um backup integral nem desligue tracking ao sair. Repetir a saída é seguro.
+3. Faça uma nova chamada nativa de leitura. Confira `.local/hooks/activation/PreToolUse.json` e o recibo de observação da sessão/turno realmente vistos. Se os hooks estiverem desligados na interface, peça sua reativação e deixe a validação pendente; não falsifique recibos. Não execute comandos destrutivos, de energia do computador ou publicações como teste.
+4. A partir da chamada seguinte, volte a aplicar a governança ativa. Informe estado final, testes observados e qualquer lacuna de telemetria. Não declare encerramento de Tasks/SPECs históricas nem totais finais de consumo sem prova.
+
+Se houver falha, execute `status` e leia o erro. A gravação atômica mantém a configuração anterior quando a substituição falha; uma interrupção posterior pode deixar a transição aplicada e o recibo pendente. Repita a mesma operação após resolver a causa. Lock ocupado impede transições simultâneas: verifique o processo registrado, sem apagar um lock de processo ativo. Nunca desligue os hooks ou tracking para contornar o erro.

package/templates/.agents/skills/zaip-skill-maintenance-exit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Sair da manutenção"
+  short_description: "Reativa o ZAIP preservando a telemetria"
+  default_prompt: "Use $zaip-skill-maintenance-exit para sair da manutenção e verificar o ZAIP ativo."

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

@@ -5,6 +5,12 @@ description: Create, refine, prepare, or analyze a ZAIP PRD on explicit PRD work
 
 # Trabalhar com PRDs
 
+Antes de promover um PRD novo, aplique o aceite binário `proportional-acceptance-v1` de `@zaip-ai/specs` conforme `docs/quality/production-readiness.md` via `zaip plan build --acceptance <contrato.json>` e valide o plano embutido. Registre por outcome obrigatório origem, aplicabilidade, resultado observável, prova suficiente, responsável e condição de parada. Só adicione obrigação ligada ao pedido, Requirement ativo ou risco concreto. Melhoria opcional não bloqueia a promoção; resultado ausente não é aprovação. Preserve snapshots anteriores até migração explícita versionada e atribuída.
+
+Ao definir ACs, selecione testes de código e fluxos de dashboard pelo impacto; a
+qualificação integral do pacote pertence ao candidato final antes da publicação.
+Reuso de prova exige identidade e contrato ainda válidos.
+
 PRD é opcional e permanece em Definição com `status: draft` durante criação, revisão, refinamento e `prepare`. Ter SPECs ou PreparedPlan válido não autoriza promoção.
 
 ## Limite de autoridade