@zaip-ai/cli 4.9.0 → 5.1.0

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-release-qualification/SKILL.md

@@ -71,6 +71,8 @@ The framework release cut uses `node scripts/release-cycle-gate.mjs freeze --rep
 
 For an authorized Task-first request that combines a product fix and its release in one direct Task root, use the explicit `--integrated-task` freeze option with that Task and active root Run. The Task must be critical, target the current release, own the release-cycle config scope and have a delivery Execution bound to its Change. `audit` and `advance` authenticate its committed Task and Run start, while all other current-release work, secondary worktrees and remote branches still block. This route avoids creating a second root Run or asking the user for a new turn solely to publish already authorized work. Do not use it for a delegated SPEC release Task or as a general waiver for release checks.
 
+For an authorized SPEC whose final critical Task combines implementation and publication, use the separate explicit `--integrated-spec-task` option with its delegated delivery Run. It requires the exact active macro Run, SPEC, Change and delivery Execution, a unique terminal Task in the committed DAG, all predecessors completed, the current target release and the literal `.agents/config/release-cycle.json` write scope. The persisted `integrated_spec_task` mode is rechecked at audit and advance; unknown modes fail closed. It cannot be combined with `--integrated-task`, which remains exclusive to direct Task roots. Broad product scopes alone never grant this mode. Clean candidate, committed coordinator records, unrelated open-work exclusion, exact-SHA CI, signed artifact and npm gates remain mandatory.
+
 For the one-time 4.5→4.6 recovery, `adopt-published` requires the published 4.5 tag to be an ancestor of remote `main`, remote `main` to be an ancestor of clean local `main`, and observed stable GitHub Release/npm integrity. Pass the exact owner `--owner-spec`, `--owner-execution`, `--owner-run`, planned `--release-task` and active delegated Task orchestrator `--actor-run`. That actor must own the release Task's unique direct predecessor; all earlier DAG Tasks must be completed. Only the actor Task, planned release Task and owner SPEC are exempt from the open-work gate. After review/Evidence and a clean metadata checkpoint, perform adoption while that predecessor Task and its actor Run are still active. Then use `spec retarget-release SPEC --from 4.5 --to 4.6 --run DELEGATED_TASK_RUN` with the same actor Run. Close the predecessor Task through Gui only after retarget; start the release Task afterward. The revision records adoption SHA and actor Run, and the release Task's missing target resolves through its owner SPEC. Do not edit records directly to retarget.
 
 After exact Release, npm and candidate CI are observed, `advance --from N.N --to NEXT --sha CANDIDATE --ci-run-id ID` opens the next cycle while the coordinator remains active. Bind Task/SPEC Evidence to the immutable published candidate before Gui, then close Task and parent SPEC. Make one reviewed metadata-only closure commit; push that exact local main SHA through `scripts/local-release-deploy.mjs push-closure` with published SHA, expected remote SHA and the exact metadata path inventory. The tag remains on the published candidate. Confirm CI on the new main SHA; local closure alone is not complete publication. This contract does not prove provider deployment.

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

@@ -6,7 +6,7 @@ Preparation does not authorize publication. Use guarded delivery only for the re
 
 The project-owned `.agents/config/deploy-policy.json` (schema version 1, `default_mode: auto|commits|release`) is separate from the builder's signed qualification policy below. Installing skills in a consumer never grants builder capability or requires builder keys/protected settings.
 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.
+every gate is bound to the resulting clean SHA. Before expensive gates, validate the active coordinator route: release-only, direct `--integrated-task`, or final SPEC `--integrated-spec-task` as defined in the canonical qualification skill. Repair changes require a new candidate.
 Qualification uses an independent local Git clone at that exact SHA, with copied
 objects and complete commit history, not a worktree sharing the caller's registry.
 This prevents dashboard source discovery from importing the main checkout or other
@@ -15,7 +15,7 @@ unchanged. Cleanup retries transient Windows locks and preserves the original ga
 error if cleanup also fails. A cleanup failure never produces a success receipt.
 
 When the ZAIP Codex PreToolUse hook is enabled, run release preparation, verification and
-guarded delivery as separate literal commands. Its external-path exception is limited to
+guarded delivery as separate literal commands. In repository-restricted profiles, its external-path exception is limited to
 the reviewed release helpers, the declared SHA and version, the matching candidate
 directory under `~/.codex/release-candidates/zaip-aios/`, and key material under
 `~/.codex/release-keys/zaip-aios/<key-id>/`. It does not permit arbitrary home
@@ -24,10 +24,19 @@ unrelated path or compound command is an intentional safety decision, not a fail
 release gate. Persistent repository edits additionally require a current Task Run with
 the exact Codex thread and turn correlation.
 
+The configured `zaip-aios-full-access` profile also permits ordinary external
+read/write/execute, working-directory, and network access. The restrictions above
+describe the narrow exception for repository-restricted profiles, not a blanket
+denial of configured full access. Neither profile bypasses secret protection,
+destructive-operation controls, lifecycle authority, stricter child permissions,
+or the ban on computer power/session actions. Release helpers still verify
+their exact repository, candidate, signing material, receipt, and authorization.
+
 For native `exec_command`, the hook validates both the chat's `cwd` and the command's
 explicit absolute `workdir`. A registered worktree may be the execution root even
 when the chat remains in the primary checkout. Unregistered roots, links, relative
-overrides and missing exact worktree Run authority remain blocked; a primary
+overrides remain subject to the configured access profile. Missing exact worktree
+Run authority for governed product mutations remains blocked; a primary
 checkout's Task is never a global fallback for mutations in another checkout.
 
 Some hosts present these commands as `Bash` without exposing a workdir override.
@@ -35,14 +44,15 @@ In that case, invoke the literal reviewed helper from the chat checkout and pass
 the registered worktree in `--repository`. Only the helper may target that explicit
 root, after physical-root, Git registration and common-directory verification;
 its own preflight checks the exact clean SHA before any gate. This is not an
-exception for arbitrary commands or filesystem access.
+exception for arbitrary commands or filesystem access in a restricted profile.
 
 ## Verified builder signing material
 
 The following key and protected-policy requirements apply only to the verified ZAIP builder, not ordinary consumer GitHub releases.
 
 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`.
+`gh variable get ZAIP_LOCAL_RELEASE_TRUSTED_KEY_ID` from the verified builder
+checkout after checking its configured origin.
 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
@@ -173,8 +183,11 @@ node scripts/local-release-preparation.mjs stage-inputs --sha <40-character-sha>
 
 `stage-inputs` accepts no source, receipt, output, home, key or policy path flags. It
 derives the candidate directory, verifies clean `main`, canonical origin, the signed
-receipt, v4.6 essential profile, trusted `maintainer-v4` key and policy digest, the
-exact release inventory, and a direct human request resolved as builder Release 4.6.
+receipt, the selected essential profile, trusted `maintainer-v4` key and policy digest,
+the exact release inventory, and a direct human request resolved as that builder Release.
+Explicit major transitions such as `4.9 → 5.0` are supported. The inventory must
+start at the highest canonical stable ancestor tag below the requested version;
+prerelease, unmerged, future and stale-range tags cannot substitute for it.
 It installs `deploy-request.txt`, `release-notes.md`, `release-inventory.json` and
 `deploy-contract.json` inside that candidate directory with complete-byte readback,
 idempotent retry and conflict rejection. The protected release helper reads the
@@ -191,11 +204,27 @@ node scripts/local-release-deploy.mjs --repository <absolute-repository> --expec
 `--dry-run` prepares and verifies without sending. The live command verifies again around
 delivery, sends the exact SHA, verifies the remote, creates a draft GitHub Release, uploads all
 four assets and publishes the release. Existing incompatible tags/assets fail without overwrite.
-The helper never invokes local npm publication.
+The helper never invokes local npm publication. Durable `release-stage-*.json`
+observations bind SHA/version/receipt digest and never replace fresh verification.
+A retry recognizes an exact remote push, uploads only absent matching assets and
+does not republish an already public matching Release. Conflicts fail closed.
+The four assets must be regular files in the real candidate directory. The helper
+observes npm version, latest and exact TGZ SRI with bounded propagation retries.
 Notes and inventory must satisfy [the release notes contract](../../zaip-skill-github-deploy/references/release-notes.md).
 For the first release, replace `--from` with explicit `--initial`. The helper validates the notes
 against the Git range before push and compares the draft and published bodies with those notes.
 
+After release-cycle advancement and formal closure, the single metadata-only commit uses:
+
+```text
+node scripts/local-release-deploy.mjs push-closure --repository ROOT --expected-repository zaip-ai/zaip-aios --branch main --version N.N --published-sha CANDIDATE --closure-sha CLOSURE --expected-remote-sha CANDIDATE --metadata-paths-file REVIEWED_JSON --receipt RECEIPT --tarball TGZ --policy POLICY --trust-store TRUST --notes-file NOTES --output-dir CANDIDATE_DIR
+```
+
+This rechecks the valid signed receipt against the immutable published Git tree,
+exact Release assets/body/latest, registry SRI/latest, recorded published CI and
+reviewed metadata diff. Remote main may already equal CLOSURE after interruption;
+retry then observes its CI without another push. Receipt expiry remains enforced.
+
 ## Installed consumer: independent GitHub release
 
 Auto mode defaults to commits plus push in a consumer. It needs scoped project checks and

package/templates/.agents/zaip-aios/VERSION

@@ -1 +1 @@
-4.9
+5.1

package/templates/.agents/zaip-aios/guides/10-seguranca.md

@@ -17,7 +17,7 @@ sistema operacional.
 execução de comandos dentro do perfil. Isso não é uma autorização de negócio ou
 de escopo: deploy, push/publicação, ações remotas, gastos, exclusões relevantes
 e mudanças fora do objetivo continuam exigindo pedido explícito do usuário no
-turno atual. Apps e MCPs podem manter seu próprio
+contexto vigente da sessão; a autorização continua válida enquanto seu escopo não mudar. Apps e MCPs podem manter seu próprio
 `default_tools_approval_mode = "approve"`; esse ajuste é independente da
 política de aprovação de comandos.
 
@@ -141,7 +141,7 @@ O acesso completo é mitigado por defesa em profundidade, mas nenhuma camada tor
 `zaip-aios-full-access` equivalente ao perfil restrito:
 
 1. **Autorização explícita do usuário:** mudanças externas, destrutivas, publicação, deploy,
-   gasto e mutações remotas exigem pedido explícito no turno atual.
+   gasto e mutações remotas exigem pedido explícito válido no contexto da sessão.
 2. **Escopo do repositório:** `AGENTS.md`, Rules e skills limitam o trabalho ao objetivo e
    proíbem inferir autoridade adicional a partir do acesso técnico.
 3. **Hook `PreToolUse` ativo nos dois perfis:** valida comandos e patches antes da execução; bloqueia escapes do

package/templates/.agents/zaip-aios/guides/26-qualidade-e-release.md

@@ -64,6 +64,18 @@ inválida ou integridade diferente impedem publicar. Após uma publicação
 autorizada, a confirmação do mesmo tarball usa retry finito de propagação.
 Esse controle não publica automaticamente quando a qualificação local passa.
 
+Na v5.0, o publisher mantém checkpoints por SHA, versão e hash do recibo para
+prepare/push/CI/assets/Release/npm/closure. A retomada sempre consulta o estado
+remoto e revalida a assinatura: efeitos já confirmados não são reenviados.
+Assets são quatro arquivos regulares no diretório real do candidato, com digest
+exato no GitHub; links simbólicos e conflitos bloqueiam. A transição explícita
+`4.9 → 5.0` usa a maior tag estável canônica ancestral como início do inventário.
+O fechamento exige recibo/TGZ/política/trust/notas/diretório, confere a árvore Git
+publicada e SRI/latest npm e aceita somente um commit revisado de metadados.
+Se `main` já estiver nesse fechamento, apenas observa seu CI. A validade temporal
+do recibo permanece obrigatória. Consulte a referência canônica
+`zaip-skill-release-qualification/references/local-preparation.md` para os comandos.
+
 | Objetivo | Comando da raiz e alcance |
 | --- | --- |
 | Preparar artefatos | `corepack pnpm release:artifacts` compila e gera runtime/template. Não publica nem qualifica por si só. |
@@ -249,6 +261,30 @@ com testes de correção e uma release publicada não comprovam economia ou SLA.
 Não repita automaticamente a matriz histórica falha: preserve o diagnóstico e
 defina uma medição independente com artefatos identificados e falhas observadas.
 
+## Evolução de confiabilidade e documentação
+
+A [matriz de evolução](https://github.com/zaip-ai/zaip-aios/blob/main/docs/quality/v50-documentacao-editorial.md)
+vincula as dez frentes aos seus comandos, provas, rollback e limitações.
+READMEs PT/EN descrevem o mesmo contrato: `essential-v3` por padrão,
+`full-v2` somente quando selecionado, CI na `main` exata antes da Release,
+smoke Linux do TGZ assinado antes do npm e confirmação da integridade publicada.
+Preparar e validar localmente não comprovam publicação ou ativação dos hooks.
+
+Uma Task explicitamente editorial `lite` aceita README literal ou Markdown
+em escopo documental estreito, como `docs/quality/**`; `docs/**` amplo,
+código, configuração e controles de agente não recebem a exceção. A dispensa
+da Decision de seis etapas conserva candidato, check, Evidence, revisão e Gui.
+Alterar esse mecanismo continua sendo trabalho crítico quando houver sinal de
+segurança. `draft` persiste blueprints; `ready` materializa Tasks `planned`;
+`execute` inicia o menor grão autorizado, sem inferir conclusão dos blueprints.
+
+O resolver reconhece o pedido direto de retomar a SPEC até finalizar as Tasks
+e publicar a versão explícita. Citação, negação, pergunta ou condição de
+aprovação não concedem publicação. O override vale somente para o pedido.
+Manutenção usa o mesmo `maintenance.mjs` da skill de entrada com `enter|exit`;
+tracking fica ligado e a saída exige observação nativa. `full-access` conserva
+proteções de segredos, destruição, lifecycle, filhos restritos e energia do PC.
+
 ## Ciclo corrente, limpeza e CI da main antes da Release
 
 O manifesto versionado `.agents/config/release-cycle.json` identifica `current_release` e estado `open`/`frozen` (4.5 e 4.5.0 são normalizados). Drafts de PRD/SPEC futuros são permitidos; ready/execução, novas Tasks e código exigem o release corrente. Depois de conciliar Tasks atuais, prove `main`, branches, worktrees e registros antes do candidato. Branch/worktree isolados são fechados com backup local recuperável; checkout compartilhado com diff de proveniência mista bloqueia. A existência de `main` ou de um teste verde isolado não qualifica a release.
@@ -262,3 +298,5 @@ Para congelar, use `node scripts/release-cycle-gate.mjs freeze --repository ROOT
 Nos modos ativos, depois das provas de publicação, registre validações e Evidence, realize revisão quando exigida e obtenha Gui como último filho. O host autorizado persiste a decisão real e o fechamento. Um commit posterior somente de records/metadata pode guardar esse encerramento; ele não requalifica o produto nem move a tag. O contrato executável está em `scripts/release-cycle-coordination.mjs` e `scripts/release-cycle-gate.mjs` no repositório mantenedor.
 
 Com candidato limpo em SHA exato, execute `node scripts/release-cycle-gate.mjs audit --repository ROOT --version VERSAO --sha SHA`. O deploy crítico/de release executa os checks locais nesse SHA, envia apenas `main` ao GitHub e espera `pre-main-candidate.yml` verde para o push exato antes da Release. Falha local bloqueia o push; falha de CI ou credenciais bloqueia a Release e exige reparo autorizado em `main`. Após observar tag, GitHub Release, main e CI exatos, `node scripts/release-cycle-gate.mjs advance --repository ROOT --from VERSAO --to PROXIMA --sha SHA --ci-run-id ID` registra a transição. As outras Tasks correntes devem estar terminais; somente a coordenação ativa validada acima pode permanecer aberta. Cada superfície, inclusive npm ou provedor, tem prova própria. O avanço não conclui automaticamente a Task de coordenação nem permite iniciar trabalho futuro antes da transição auditada.
+
+Uma Task final de SPEC que combine implementação e publicação usa o modo explícito `--integrated-spec-task`, descrito na skill canônica de qualificação. Verifique essa elegibilidade antes dos gates caros; mantenha os predecessores concluídos e as provas válidas. Consulte [o diagnóstico v5.0](https://github.com/zaip-ai/zaip-aios/blob/main/docs/quality/v50-retrabalho-e-publicacao.md).