@zaip-ai/cli 4.5.0 → 4.7.0

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

@@ -16,6 +16,9 @@ const managedDeployFiles = [
   "skills/zaip-skill-github-deploy/scripts/github-deploy-contract.test.mjs",
   "skills/zaip-skill-github-deploy/scripts/preflight.mjs",
   "skills/zaip-skill-github-deploy/scripts/preflight.test.mjs",
+  "skills/zaip-skill-github-deploy/scripts/deploy-contract.mjs",
+  "skills/zaip-skill-github-deploy/scripts/deploy-contract.test.mjs",
+  "skills/zaip-skill-github-deploy/scripts/guarded-commits.mjs",
 ];
 
 test("framework lock matches the deploy guidance and executable contract", async () => {
@@ -41,11 +44,14 @@ test("explicit Git publication verbs select the guarded deploy skill", async ()
     readFile(resolve(skillRoot, "agents", "openai.yaml"), "utf8"),
     readFile(resolve(root, "rules", "core.md"), "utf8"),
   ]);
-  assert.match(skill, /explicit current-turn request to `deploy`, `push`, `publicar`/);
-  assert.match(skill, /discussing or editing deployment does not authorize publication/);
+  assert.match(skill, /affirmative request to deploy, push, publish to GitHub/);
+  assert.match(
+    skill,
+    /Discussing, quoting, editing or negating a release is not publication authority/,
+  );
   assert.doesNotMatch(skill, /standing automatic deployment|activate it automatically/);
   assert.match(openai, /\$zaip-skill-github-deploy/);
-  assert.match(openai, /fa.a deploy/);
+  assert.match(openai, /deploy solicitado pela política do projeto/);
   assert.match(core, /seleciona/);
 });
 
@@ -55,13 +61,16 @@ test("deploy guidance preserves canonical Task identity and builder-versus-consu
     readFile(resolve(root, "rules", "workflow.md"), "utf8"),
   ]);
   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, /\[CODEX\|CLAUDE\]/);
+  assert.match(skill, /consumers create only their GitHub Release under their own checks/);
   assert.match(
     skill,
-    /“faça deploy” means the guarded push, GitHub Release and observation of the GitHub Actions npm publication/,
+    /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, /commitar o diff evidenciado com pathspecs explícitos/);
 });
 
 test("framework deploy follows Release-triggered npm publication without claiming partial success", async () => {
@@ -78,22 +87,25 @@ test("framework deploy follows Release-triggered npm publication without claimin
     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(skill, /publish-cli\.yml.*registry version, dist-tag and integrity/s);
+  assert.match(skill, /Release with failed or unobserved npm is partial/);
+  assert.match(
+    skill,
+    /Do not enter release qualification, change a version or create a Release merely for this mode/,
+  );
   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/);
+  assert.match(skill, /Release with failed or unobserved npm is partial/);
 });
 
-test("faça deploy authorizes the complete selected worktree with safety gates", async () => {
+test("generic deploy scopes current work; all-worktree needs an explicit request", async () => {
   const skill = await readFile(resolve(skillRoot, "SKILL.md"), "utf8");
-  assert.match(skill, /commits covering all versionable pending changes/);
-  assert.match(skill, /`git add -A`/);
-  assert.match(skill, /selected worktree is the complete publication scope/);
-  assert.match(skill, /Stop only for an unresolved index conflict/);
+  assert.match(skill, /Default scope is `current-work`/);
+  assert.match(skill, /`all-worktree` requires explicit “deploy de tudo”/);
+  assert.match(skill, /never `git add -A`/);
+  assert.match(skill, /Integrity, authentication, destructive operations/);
 });
 
 test("deploy permission and reconciliation remain explicit and recoverable", async () => {
@@ -101,20 +113,21 @@ test("deploy permission and reconciliation remain explicit and recoverable", asy
     readFile(resolve(skillRoot, "SKILL.md"), "utf8"),
     readFile(resolve(skillRoot, "agents", "openai.yaml"), "utf8"),
   ]);
-  assert.match(skill, /Mandatory authorization record/);
-  assert.match(skill, /repository, remote, branch and selected worktree/);
-  assert.match(skill, /recoverable branch reference/);
-  assert.match(skill, /preserve tracked plus untracked changes in a named stash/);
-  assert.match(skill, /Restore with `git stash apply`/);
-  assert.match(skill, /local branch, recovery branch or detached state as the source candidate/);
-  assert.match(skill, /configured deploy branch is the remote target/);
+  assert.match(skill, /Record sanitized intent, resolved mode\/scope, selected checkout/);
+  assert.match(skill, /source SHA\/branch, configured remote target/);
+  assert.match(skill, /verified recovery ref and named stash/);
+  assert.match(skill, /Restore with `stash apply`/);
+  assert.match(skill, /Source recovery branches and detached HEAD are valid candidates/);
+  assert.match(skill, /configured branch is only the remote target/);
   assert.match(openai, /\$zaip-skill-github-deploy/);
-  assert.match(openai, /builder zaip-aios.*Release.*workflow npm/);
+  assert.match(openai, /npm via Actions somente em release do builder verificado/);
 });
 
 test("workflow retains the explicit publication routing contract", async () => {
   const workflow = await readFile(resolve(root, "rules", "workflow.md"), "utf8");
-  assert.match(workflow, /deploy\|push\|publicar.*autoriza.*\$zaip-skill-github-deploy/);
+  assert.match(workflow, /\$zaip-skill-github-deploy/);
+  assert.match(workflow, /deploy-policy\.json/);
+  assert.match(workflow, /current-work/);
 });
 
 test("release guidance requires reviewed categorized notes and published-body readback", async () => {
@@ -124,9 +137,9 @@ test("release guidance requires reviewed categorized notes and published-body re
     readFile(resolve(skillRoot, "references", "release-notes.md"), "utf8"),
     readFile(resolve(skillRoot, "scripts", "validate-release-notes.mjs"), "utf8"),
   ]);
-  assert.match(skill, /Never use `--generate-notes`/);
-  assert.match(identity, /--notes-file <reviewed-notes\.md>/);
-  assert.match(identity, /--notes-file <reviewed-notes\.md>.*Never use `--generate-notes`/);
+  assert.match(skill, /never use generated notes alone/);
+  assert.match(identity, /reviewed UTF-8 notes file/);
+  assert.match(identity, /read back the body byte-for-byte/);
   assert.match(notes, /exact previous Release tag/);
   assert.match(notes, /Novidades \(feat\)/);
   assert.match(notes, /Read the release back after creation/);

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

@@ -0,0 +1,212 @@
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { commands, configuredBranch, run } from "./consumer-release-preparation.mjs";
+import { readDeploymentInput, verifyContract } from "./deploy-contract.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const git = (root, args) =>
+  execFileSync("git", args, {
+    cwd: root,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: 15000,
+  }).trim();
+function assert(ok, message) {
+  if (!ok) throw new Error(message);
+}
+function identity(root, sha) {
+  assert(/^[a-f0-9]{40}$/i.test(sha), "Exact candidate SHA required");
+  assert(
+    git(root, ["rev-parse", "HEAD"]).toLowerCase() === sha.toLowerCase(),
+    "Candidate HEAD changed",
+  );
+  assert(
+    git(root, ["status", "--porcelain"]) === "",
+    "Commit only the authorized scope before push",
+  );
+}
+export async function criticalTaskInRange(root, sha, remote = "origin") {
+  const base = git(root, ["ls-remote", remote, "refs/heads/main"]).split(/\s+/)[0];
+  assert(/^[a-f0-9]{40}$/i.test(base), "Remote main is unavailable for critical Task audit");
+  git(root, ["merge-base", "--is-ancestor", base, sha]);
+  const commits = git(root, ["rev-list", "--reverse", `${base}..${sha}`])
+    .split(/\r?\n/)
+    .filter(Boolean);
+  const ids = new Set();
+  let critical = false;
+  for (const commit of commits) {
+    const message = git(root, ["show", "-s", "--format=%B", commit]);
+    for (const match of message.matchAll(/^ZAIP-Task:\s*(TASK-[A-Z0-9-]+)\s*$/gim)) {
+      const id = match[1];
+      ids.add(id);
+      const date = /^TASK-(\d{4})-(\d{2})-/.exec(id);
+      assert(date, "Invalid Task identity in candidate");
+      const path = `.agents/records/tasks/${date[1]}/${date[2]}/${id}.md`;
+      let source;
+      try {
+        source = git(root, ["show", `${commit}:${path}`]);
+      } catch {
+        throw new Error(`Critical gate cannot verify Task record at commit: ${id}`);
+      }
+      const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)?.[1];
+      assert(
+        front && front.split(/\r?\n/).includes("id: " + id),
+        "Critical gate cannot verify Task identity at commit",
+      );
+      if (/^risk: critical\s*$/m.test(front)) critical = true;
+    }
+  }
+  for (const id of ids) {
+    const match = /^TASK-(\d{4})-(\d{2})-/.exec(id);
+    assert(match, "Invalid Task identity in candidate");
+    const path = `.agents/records/tasks/${match[1]}/${match[2]}/${id}.md`;
+    let source;
+    try {
+      source = git(root, ["show", `${sha}:${path}`]);
+    } catch {
+      throw new Error(`Critical gate cannot verify candidate Task record: ${id}`);
+    }
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)?.[1];
+    assert(
+      front && front.split(/\r?\n/).includes("id: " + id),
+      "Critical gate cannot verify candidate Task record",
+    );
+    if (/^risk: critical\s*$/m.test(front)) critical = true;
+  }
+  return critical;
+}
+/** Commit creation remains Task-owned. This route sends an already committed candidate;
+ * it never allocates a version, calls gh release or obtains npm publication credentials. */
+export async function guardedCommits(input, operations = {}) {
+  const root = resolve(input.repository);
+  const readInput = operations.readInput ?? readDeploymentInput;
+  const checkIdentity = operations.identity ?? identity;
+  const branchFor = operations.branchFor ?? configuredBranch;
+  const checkCommands = commands(input.checks);
+  assert(/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(input.remote ?? "origin"), "Invalid remote name");
+  const initial = await readInput(root, input.request);
+  verifyContract(input.plan, initial, "commits", input.dryRun ? input.plan.phase : "publish");
+  assert(input.plan.phase === "publish" || input.dryRun, "Preparation never sends commits");
+  const branch = await branchFor(root, input.scope ?? "frontend");
+  assert(branch === input.branch, "Target must match the current project branch");
+  checkIdentity(root, input.sha);
+  await (operations.checks ?? ((items) => run(items, root, "scoped commit validation")))(
+    checkCommands,
+  );
+  checkIdentity(root, input.sha);
+  const recheck = async () => {
+    verifyContract(input.plan, await readInput(root, input.request), "commits", input.plan.phase);
+    assert(
+      (await branchFor(root, input.scope ?? "frontend")) === branch,
+      "Configured target changed",
+    );
+    checkIdentity(root, input.sha);
+  };
+  await recheck();
+  if (input.dryRun) return { mode: "commits", verified: true, pushed: false, release: false };
+  await (
+    operations.preflight ??
+    (() =>
+      execFileSync(
+        process.execPath,
+        [
+          resolve(here, "preflight.mjs"),
+          "--repository",
+          root,
+          "--remote",
+          input.remote ?? "origin",
+          "--scope",
+          input.scope ?? "frontend",
+          "--branch",
+          branch,
+        ],
+        { cwd: root, windowsHide: true, stdio: "inherit" },
+      ))
+  )();
+  await recheck();
+  const critical =
+    input.plan.kind === "builder" &&
+    (await (operations.isCritical ?? criticalTaskInRange)(
+      root,
+      input.sha,
+      input.remote ?? "origin",
+    ));
+  const candidateGate = critical
+    ? await import(pathToFileURL(resolve(root, "scripts/remote-candidate-gate.mjs")).href)
+    : null;
+  if (critical) {
+    await (operations.qualifyPreMain ?? candidateGate.qualifyLocalCandidate)({
+      repository: root,
+      sha: input.sha,
+      kind: "critical",
+      remote: input.remote ?? "origin",
+    });
+    await recheck();
+  }
+  const refspec = `${input.sha}:refs/heads/${branch}`;
+  await (
+    operations.push ??
+    (() =>
+      execFileSync("git", ["push", input.remote ?? "origin", refspec], {
+        cwd: root,
+        windowsHide: true,
+        stdio: "inherit",
+      }))
+  )({ repository: root, refspec });
+  const remoteSha = await (
+    operations.remoteSha ??
+    (() =>
+      git(root, ["ls-remote", input.remote ?? "origin", `refs/heads/${branch}`]).split(/\s+/)[0])
+  )();
+  assert(
+    remoteSha === input.sha.toLowerCase(),
+    "Remote SHA does not match the delivered candidate",
+  );
+  if (critical) {
+    await (operations.verifyMainCi ?? candidateGate.waitMainCandidate)({
+      repository: root,
+      sha: input.sha,
+      kind: "critical",
+      remote: input.remote ?? "origin",
+    });
+  }
+  return { mode: "commits", verified: true, pushed: true, release: false, sha: input.sha };
+}
+async function main() {
+  const { values } = parseArgs({
+    strict: true,
+    options: {
+      repository: { type: "string", default: "." },
+      sha: { type: "string" },
+      branch: { type: "string" },
+      scope: { type: "string", default: "frontend" },
+      remote: { type: "string", default: "origin" },
+      "request-file": { type: "string" },
+      "plan-file": { type: "string" },
+      "checks-file": { type: "string" },
+      "dry-run": { type: "boolean", default: false },
+    },
+  });
+  for (const field of ["sha", "branch", "request-file", "plan-file", "checks-file"])
+    assert(values[field], `--${field} is required`);
+  const result = await guardedCommits({
+    repository: values.repository,
+    sha: values.sha,
+    branch: values.branch,
+    scope: values.scope,
+    remote: values.remote,
+    dryRun: values["dry-run"],
+    request: await readFile(resolve(values["request-file"]), "utf8"),
+    plan: JSON.parse(await readFile(resolve(values["plan-file"]), "utf8")),
+    checks: JSON.parse(await readFile(resolve(values["checks-file"]), "utf8")),
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });

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

@@ -38,6 +38,10 @@ the supplied ID and canonical record; never scan ordinary history to guess a tar
    a chain of cleanup Tasks to compensate for an incomplete scope or preparation error.
    Await every delegated result, make the finalizer the last child, and only report
    closure after all owned work is terminal. A progress handoff is not completion.
+9. Before dispatching the finalizer, run the known candidate gates and repair failures
+   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.
 
 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-prd/SKILL.md

@@ -64,3 +64,7 @@ Ao receber “execute esse PRD”, inclusive no mesmo turno da preparação, reu
 # Referência visual condicional
 
 Quando a PRD citar UI ou referência visual, registre rota/aba, família de componente, colunas/linhas/paginação, estados e responsividade como invariantes observáveis, sem prometer prova visual inexistente.
+
+## Release alvo
+
+Ao criar PRD, registre `--target-release major.minor`; sem opção, a CLI usa a release corrente de `.agents/config/release-cycle.json`. Um alvo futuro, por exemplo `4.6` enquanto `4.5` está corrente, pode manter PRD e SPECs filhas em `draft`, inclusive com PreparedPlan. `prd ready` e `prd execute` falham antes de materializar Tasks até que a transição auditada torne `4.6` corrente. As SPECs selecionadas devem carregar o mesmo alvo. Não antecipe código futuro para a release corrente só para contornar o gate.

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

@@ -1,74 +1,52 @@
 ---
 name: zaip-skill-release-qualification
-description: Qualify an exact ZAIP release candidate through source-template-package parity, cleanroom, smoke, and candidate-specific evidence; use before a release or publication decision.
+description: Qualify a release candidate after deploy mode resolution or an explicit preparation request; verify exact-candidate evidence for the actual builder or consumer distribution surface without publishing.
 ---
 
 # Qualify a release candidate
 
-Use before deciding whether a concrete candidate is ready. It does not publish.
-
-For the framework installer, first apply `zaip-skill-update-version-doc` and its
-executable source check. Candidate identity comes from the root manifest;
-generated artifact hashes and exact-package proof remain mandatory below.
-
-This skill is mandatory before every frontend/backend GitHub deploy and framework release.
-Follow [the executable preparation guide](references/local-preparation.md). Synchronize and commit
-the candidate first. The framework helper runs fixed gates in an isolated checkout, builds the
-package once, validates that TGZ, and signs its receipt. A valid cache requires the same candidate,
-policy, gate definitions, runtime, channel, version, trusted key, expiry and artifact digests.
-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.
-
-The only public npm package is `@zaip-ai/cli`; the installation entry point is
-`npx @zaip-ai/cli@latest init`. Verify that release automation, manifests, and
-registry checks target only this package before qualifying the next publication.
-
-## Proportional validation
-
-Local framework preparation defaults to signed `essential-v3`: deterministic source, lock,
-build/type checks, package/SBOM/TGZ integrity, dependency audit and one clean installed-consumer
-doctor/SQLite/API smoke. It deliberately does not certify every dashboard tab or XLSX export.
-Use `--profile full` only for an explicit extended `full-v2` qualification; it retains
-`pnpm qualify:full`, browser and XLSX coverage. The profile, fixed gate list and artifact digests
-are signed, so an old `full-v2` or rapid receipt cannot satisfy the new default by accident.
-The default legacy GitHub path retains its separate full receipt and exact-TGZ matrix. Rapid
-checks remain diagnostics, never release receipts; timeouts fail visibly.
-Follow [local preparation](references/local-preparation.md) for budgets, exact-candidate
-evidence and cache validity. A failed or timed-out gate emits no success receipt.
-Report local qualification, runtime matrix, GitHub and publication outcomes separately.
-
-## Guarded local qualification and single remote smoke
-
-An administrator explicitly enables `ZAIP_LOCAL_RELEASE_ENABLED=true` after signed essential
-local qualification and public trust enrollment. The guarded helper publishes the exact signed
-GitHub Release assets. The read-only verifier validates receipt, policy, SHA and TGZ,
-then runs one Linux installation/doctor smoke before the isolated npm job receives
-publication credentials. No private-draft pilot or contents-write token is required.
-The publisher reverifies artifacts and registry integrity; additional registry installation
-is opt-in manual `extended_verification=true`. Missing proof never falls back to publishing.
-A published GitHub Release alone does not prove npm delivery. Never upload a private key.
-
-1. Identify the exact candidate revision, version, and intended distribution surface.
-   Do not substitute current working-tree checks for candidate evidence.
-2. Validate framework lock, source-to-public-template parity, generated artifacts,
-   package contents, and version alignment. Treat any source/template/package drift as
-   a failed candidate.
-3. Run the relevant smoke and cleanroom checks against that candidate and preserve the
-   commands, revision, outcomes, and unresolved limits as evidence.
-4. Separate local qualification, remote GitHub CI, registry publication, and formal
-   lifecycle closure. A matching SHA or passing local gate does not prove terminal CI.
-5. Route an explicit push, deploy, or GitHub publication request to
-   `$zaip-skill-github-deploy`; never publish as part of qualification. Consumers remain independent
-   and GitHub-only. A framework candidate maps its helper-resolved `vN.N` tag to package `N.N.0`, and
-   only the qualified GitHub Actions workflow may publish `@zaip-ai/cli` to npm; no local npm command
-   may publish it.
+Use after `$zaip-skill-github-deploy` resolves release mode, or when local preparation/qualification is explicitly requested. Resolve deploy mode first using [the deployment contract](../zaip-skill-github-deploy/references/deployment-workflow.md). Generic consumer deploy under auto and explicit commits mode use scoped checks and `guarded-commits.mjs`; they do not acquire a release gate from this skill.
+
+Preparation, verification and dry-run do not publish. The request's resolved route supplies publication authority separately.
+
+## Select the distribution surface
+
+- Verified ZAIP builder requires approved `zaip-ai/zaip-aios` origin and both `@zaip-ai/aios` root/`@zaip-ai/cli` public CLI package identities. Apply `zaip-skill-update-version-doc`; root manifest defines candidate `N.N.0`, aligned to GitHub `vN.N`.
+- Consumers use their actual project checks and GitHub release contract. They have no builder npm, TGZ, signing-key or protected-policy requirements. Existing project-specific signed preparation applies only when that project adopted it.
+- Contradictory identity blocks routing. Never infer builder capability from a project name or installed skills, and never infer beta creation. Application targets follow literal project configuration, including main.
+
+Read [local preparation](references/local-preparation.md) for the selected surface. Synchronize and commit first; evidence must bind the clean exact candidate. An already-published candidate SHA is a no-op, not a reason to allocate an empty new Release. Retry/resume preserves the exact SHA and assigned identity.
+
+## Builder release qualification
+
+Local builder preparation defaults to signed `essential-v3`: deterministic source/lock/parity, build/type integrity, dependency audit, prioritized installer/rollback/release regressions, package/SBOM/TGZ binding and one clean installed-consumer doctor/SQLite/API smoke.
+
+These dense distribution checks are release gates. Change validation outside release remains targeted, with installer/security checks selected when directly impacted. Do not automatically run the full suite for generic commits, impose a test-count ceiling or classify a Task by wallclock duration.
+
+Use `--profile full` for explicitly requested extended `full-v2` qualification, including full source, browser and XLSX coverage. Changed dashboard/export behavior still needs its relevant tests in the current Change. Rapid impact checks emit no signed release receipt and cannot substitute for release qualification.
+
+The framework helper uses an isolated exact-SHA clone, builds once, verifies the exact TGZ and signs a receipt. Cache validity requires matching candidate, policy, gate definitions, runtime, channel, version, trusted key, expiry and artifact digests. Failed/timed-out gates emit no successful receipt; changed candidates or invalid evidence require new qualification.
+
+Resolve builder signing material from the configured stable private directory and run `scripts/local-release-key.mjs preflight` before expensive gates. Inspect actual key/trust/policy configuration before claiming absence. Missing/mismatched required material fails closed; never generate replacement keys, rotate trust or remove signatures during routine deploy.
+
+## Protected publisher and evidence
+
+The reduced path is explicitly enabled by an administrator after signed qualification and public trust enrollment. Its helper publishes exact signed Release assets; a read-only GitHub verifier validates policy/SHA/TGZ and runs one Linux installation/doctor smoke before the isolated npm job gets credentials. No private-draft pilot is required. Keep the existing protected route; ordinary requested deploy needs no repeated pipeline confirmation.
+
+Where the legacy path remains configured, retain its separate exact-candidate qualification receipt and matrix. Extended GitHub qualification is manual-only. An optional registry installation is explicit; registry digest and channel verification remain mandatory in builder publication. Only GitHub Actions publishes `@zaip-ai/cli`; never upload private keys or publish npm locally.
+
+1. Identify exact revision, version, target and actual distribution surface; do not substitute current dirty-worktree checks.
+2. Prove the selected checks, candidate-bound artifact integrity and source/template/package parity where the builder requires it.
+3. Preserve actual commands, candidate, environment, outcomes and limits as evidence; unavailable checks stay unverified.
+4. Separate local qualification, remote CI, registry publication and formal lifecycle closure. A passed local check or Release URL alone proves none of the other outcomes.
+5. Return the qualification result to the resolved deploy route. Consumer GitHub release stays independent; builder delivery binds SHA/tag/version/digest and observes npm terminal status.
+
+Recover under the frozen Task autonomy profile: balanced permits 10 executions total and 3 replans. Individual tests/tool calls and elapsed time are not executions, and continuation never resets the ledger.
+
+The framework release cut uses `node scripts/release-cycle-gate.mjs freeze --repository ROOT --version N.N --release-task TASK-ID --release-run RUN-ID`. The exceptional coordinator is the critical, release-only Task at the end of the owner SPEC's exact Execution DAG. Every predecessor Task must be completed; only the release Task may still execute. Its delegated Task orchestrator Run must be active under that SPEC's active macro Run. `audit` and `advance` recheck predecessor status and authenticate the same Task, Run, SPEC, Execution and committed candidate records; only the release Task and owner SPEC are exempt from the open-work gate. Unrelated work remains blocked. The candidate commits the frozen cycle before qualification. The deploy helper checks its exact SHA, pushes only `main`, and requires successful CI on that SHA before publication.
+
+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 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.