@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/skills/zaip-skill-github-actions-setup/scripts/verify-ssh.integration.test.mjs

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import test from "node:test";
+
+function findBash() {
+  if (process.platform !== "win32") return "bash";
+  const git = spawnSync("where.exe", ["git.exe"], { encoding: "utf8" });
+  const candidates = (git.stdout ?? "")
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .flatMap((file) => [
+      resolve(dirname(file), "../bin/bash.exe"),
+      resolve(dirname(file), "../../bin/bash.exe"),
+    ]);
+  const match = candidates.find(existsSync);
+  assert.ok(match, "Git for Windows with Bash must be available on PATH for this integration test");
+  return match;
+}
+const bash = findBash();
+const guide = await readFile(new URL("../references/hostinger-vps.md", import.meta.url), "utf8");
+const snippet = guide.match(/```bash\n([\s\S]*?)\n```/)[1];
+const toPosix = (value) =>
+  process.platform === "win32"
+    ? value.replaceAll("\\", "/").replace(/^([A-Za-z]):/, (_, drive) => "/" + drive.toLowerCase())
+    : value;
+
+async function runProbe(overrides = {}) {
+  const dir = await mkdtemp(join(tmpdir(), "zaip-ssh-probe-"));
+  const stub = join(dir, "ssh");
+  // Execute the actual guide snippet, substituting only the external SSH process.
+  await writeFile(
+    stub,
+    '#!/usr/bin/env bash\nset -eu\nprintf "%s\\n" "$@" > "$PROBE_ARGS"\ntest -s "$4"\nprintf "%s" "$4" > "$PROBE_KEY_PATH"\nif env | grep -q "^VPS_SSH_PRIVATE_KEY="; then exit 99; fi\nexit "${PROBE_EXIT:-0}"\n',
+  );
+  await chmod(stub, 0o700);
+  const script = join(dir, "probe.sh");
+  await writeFile(script, 'export PATH="' + toPosix(dir) + ':$PATH"\n' + snippet);
+  const argsFile = join(dir, "args.txt");
+  const keyPathFile = join(dir, "key-path.txt");
+  const child = spawnSync(bash, [toPosix(script)], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      VPS_HOST: "example.invalid",
+      VPS_PORT: "2222",
+      VPS_USER: "deploy",
+      VPS_SSH_PRIVATE_KEY: "synthetic-multiline\nprivate-key",
+      VPS_KNOWN_HOSTS: "[example.invalid]:2222 ssh-ed25519 synthetic-public",
+      PROBE_ARGS: toPosix(argsFile),
+      PROBE_KEY_PATH: toPosix(keyPathFile),
+      ...overrides,
+    },
+  });
+  let args = null;
+  try {
+    args = await readFile(argsFile, "utf8");
+  } catch {}
+  let cleanupExit = null;
+  try {
+    const keyPath = await readFile(keyPathFile, "utf8");
+    cleanupExit = spawnSync(bash, [
+      "-c",
+      'test ! -e "$1" && test ! -d "$(dirname "$1")"',
+      "--",
+      keyPath,
+    ]).status;
+  } catch {}
+  assert.equal(dirname(resolve(dir)), resolve(tmpdir()));
+  assert.ok(basename(dir).startsWith("zaip-ssh-probe-"));
+  await rm(dir, { recursive: true, force: true });
+  return { ...child, args, cleanupExit };
+}
+
+test("guide SSH test uses verified host, fixed read-only command and cleans key", async () => {
+  const result = await runProbe();
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.args, /StrictHostKeyChecking=yes/);
+  assert.match(result.args, /BatchMode=yes/);
+  assert.match(result.args, /deploy@example.invalid\ntrue\n$/);
+  assert.equal(result.cleanupExit, 0);
+  assert.ok(!result.stdout.includes("private-key"));
+});
+
+test("SSH failure is propagated and private material removed", async () => {
+  const result = await runProbe({ PROBE_EXIT: "255" });
+  assert.equal(result.status, 255, result.stderr);
+  assert.equal(result.cleanupExit, 0);
+});
+
+for (const fields of [
+  { VPS_HOST: "-oProxyCommand=bad" },
+  { VPS_USER: "deploy;bad" },
+  { VPS_PORT: "0" },
+  { VPS_PORT: "65536" },
+  { VPS_PORT: "22;bad" },
+])
+  test("invalid SSH destination never executes SSH: " + JSON.stringify(fields), async () => {
+    const result = await runProbe(fields);
+    assert.equal(result.status, 2, result.stderr);
+    assert.equal(result.args, null);
+  });

package/templates/.agents/skills/zaip-skill-github-deploy/SKILL.md

@@ -5,99 +5,65 @@ description: Use only when the user explicitly asks in the current turn to deplo
 
 # Deploy and repair GitHub publication
 
-The exact command “faça deploy” authorizes publication of everything versionable in the selected worktree, including tracked and untracked files, after the safety gates below. It does not authorize provider deployment.
+Treat deploy as Git-only publication. An explicit current-turn request to `deploy`, `push`, `publicar`, `publicação` or GitHub publication selects this skill. It never authorizes provider deployment.
 
-Treat deploy as Git-only publication. An explicit current-turn request to `deploy`, `push`, `publicar`, `publicação` or GitHub publication selects this skill; it authorizes only the bounded Git publication described below, never a provider deployment or automatic publication.
+Read [the deployment workflow](references/deployment-workflow.md) for the detailed operational contract before publication. The steps below retain its authority, identity and completion boundaries.
 
-## Authorization
+## Authorization and scope
 
-- Require an explicit deploy, push, publicar, publicação, GitHub publication, or failed-deploy repair request in the current turn.
-- The request authorizes the initial publication, automatic reconciliation needed to publish the selected branch, commits covering all versionable pending changes in the selected worktree, and up to five repair cycles needed to make required local and remote GitHub checks pass. Do not stop merely because the worktree is dirty, history is behind/diverged, generated files are pending, or a local gate has a repairable failure.
-- Limit repairs to the intended repository state and the evidenced failure. Do not add unrelated features or broaden product scope.
+- The exact command “faça deploy” authorizes commits covering all versionable pending changes in the selected worktree, followed by push and Release, after secret, size and ignore checks. The selected worktree is the complete publication scope; other worktrees remain outside it.
+- Resolve dirty state, untracked files, generated projections, branch divergence and repairable local/remote failures automatically within that scope. Limit repairs to the evidenced cause, with up to five repair cycles; stop when the same root cause remains after two repairs.
+- Stop only for an unresolved index conflict after bounded repair, secrets, files at or above GitHub's 100 MB limit, unavailable authentication/authority, external outage, destructive requirement, or ambiguous scope expansion.
 - Never force push, rewrite history, replace remotes, change credentials or Git/SSH configuration, bypass checks, or deploy to another service.
-- Do not create lifecycle artifacts for an explicit Git-only publication request. The deploy authorization permits staging every inventoried versionable path in the selected worktree after secret, size, and ignore checks; it never authorizes changes outside that worktree.
-- Map a functional group to PRD/SPEC/Task only when evidence exists; otherwise use `[CODEX] <functional title>` without `ZAIP-Task`. Omit nonexistent lineage blocks and trailers. Complete inventoried-path staging is authorized only by the exact current-turn deploy request; force, destructive reset, history rewrite, and credential changes remain prohibited.
+- Git-only publication of existing commits needs no artificial Task. Product edits or new product commits require real Task ownership; materialize missing authorized work before editing. Records/local-only snapshots are exempt.
 
 ## Mandatory authorization record
 
-Before the first Git mutation, retain a sanitized authorization record in the task's visible progress and terminal report. It must state:
+Before the first Git mutation, retain sanitized authority in progress and the terminal report: current-turn intent; repository, remote, branch and selected worktree; push-only versus commit plus push; bounded rebase (default) or user-selected merge; allowed repairs and excluded scopes; preflight result and preservation reference. Never record credentials or environment values.
 
-1. the user's current-turn publication intent;
-2. repository, remote, branch and selected worktree;
-3. whether the grant is simple push or partitioned commit plus push;
-4. the bounded history-reconciliation strategy (`rebase` by default, or user-selected `merge`);
-5. allowed repair cycles, excluded worktrees/scopes and prohibited actions;
-6. the preflight result and the recoverable preservation reference used before reconciliation.
+## Prepare the selected worktree
 
-The conversation and terminal deploy report are the authority record for Git-only publication; do not create lifecycle artifacts or store credentials, private-key contents, tokens or environment values. If any required permission is absent, stop at the read-only diagnosis and request only the missing authority.
+1. Inspect Git status, pending paths and diff summary. Review every inventoried versionable file for secrets, size and ignore policy.
+2. Read `.agents/config/project.yaml`. Resolve the explicit frontend/backend scope from `deploy.frontend.branch` or `deploy.backend.branch`; configured `main` is permitted. `deploy.database.branch` must remain literal `beta`. The legacy `deploy.branch` fallback remains non-production.
+3. Prove folder-scoped SSH using `scripts/preflight.mjs --repository . --remote origin --scope frontend` (or the actual authorized scope). Run at most once per cycle; recheck only after an evidenced repair or changed target. Require SSH origin, configured key, Git identity and successful `ls-remote`; no process overrides or credential/config edits.
+4. Fetch once per cycle and compute ahead/behind. Before reconciliation, create a recoverable branch reference and preserve tracked plus untracked changes in a named stash. Use bounded rebase by default. Restore with `git stash apply`; verify preservation, retain the stash until success, and combine conflicts from observed intent. Never reset or force.
+5. Re-inventory after reconciliation. Stage the reviewed paths with `git add -- <explicit-pathspecs>`; never use `git add -A`, `git add -u`, broad globs or ignored files. Explicit deploy permits the whole inventoried selected worktree, without mandatory functional partitioning.
+6. Run required or evidenced gates only. Reuse unchanged valid evidence; bypass Turbo cache for the failed remote gate when repairing CI. A failed gate starts a new cycle only after a concrete repair or new remote evidence.
 
-## Multiple worktrees and divergent history
+## Task identity in commits
 
-1. Run `git worktree list --porcelain` and inspect `git status --porcelain` in every existing worktree before staging.
-2. Select exactly one publishing worktree. A clean worktree on another branch or a detached verification worktree does not join the deploy. The selected worktree is the complete publication scope.
-3. Report concurrent activity, but do not block solely because the selected worktree is dirty or contains mixed changes; the explicit “faça deploy” authorization includes those changes. Stop only for an unresolved index conflict, secret/oversize file, authentication failure, or destructive/rewrite requirement.
-4. Prunable or missing worktrees are reported but never pruned automatically. Dirty detached or temporary worktrees are never deleted, reset, stashed or copied into the publishing worktree implicitly.
-5. Fetch once and compute ahead/behind for the publishing branch. If it is behind or diverged, automatically reconcile only the selected branch under this deploy authorization and continue; divergence is not a blocker by itself.
-6. Before reconciliation, create a recoverable branch reference and preserve tracked plus untracked changes in a named stash. Verify both references before proceeding. Use `rebase` unless the user explicitly selected `merge`.
-7. Apply the bounded reconciliation without force. Restore with `git stash apply`, retain the stash until publication succeeds, and resolve generated aggregate conflicts by regenerating them from canonical sources. For ordinary textual conflicts, combine both sides when safe; use the selected worktree's intended version only when the diff and commit history establish that it supersedes the remote version.
-8. After restoration, prove that no unmerged paths remain, re-inventory the diff, and only then begin functional partitioning. Continue automatically through recoverable conflicts and pending repairs; stop only for a genuine terminal blocker defined below.
+Use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>` with evidenced lineage. The effective prefix is exclusively `CODEX` or `CLAUDE`; `AUTO` is not part of this policy.
 
-## Repair-loop integrity
+Standalone Tasks use `[Task-first:XXXX]` followed by the canonical Task title; do not invent PRD/SPEC lineage. Keep the subject within 96 characters and full IDs in `ZAIP-*` trailers. Use `task commit TASK --run RUN --files PATHS`, retain the commit-msg hook, and validate the range with `commit validate`.
 
-- A publication cycle is: run deploy preflight, inventory the intended pending diff, synchronize, create any required functional commits with explicit pathspecs, push, and verify the remote hash. When no intended pending diff exists, publish already-formed commits. Run only gates required or evidenced by repository Rules, the active Change, or failed remote CI.
-- Inventory the complete pending diff, run the safety gates, then stage the reviewed inventory with `git add -- <explicit-pathspecs>` and commit it. Generate pathspecs from the reviewed tracked and untracked inventory; do not use `git add -A`, broad globs, or paths outside the selected worktree. Do not require functional partitioning for this explicit broad-deploy mode.
-- Run each diagnostic, gate, fetch, stage, commit, push, and hash verification at most once per cycle.
-- Start a new cycle only after a repository change or new remote evidence. Never repeat an unchanged failing command hoping for a different result.
-- Continue until all required checks pass or a terminal blocker occurs. Stop after five repair cycles, or when the same root cause remains after two repairs.
-- Treat authentication, unavailable credentials, unresolved conflicts after bounded repair, secret exposure, destructive changes, GitHub outages, and ambiguous scope expansion as terminal blockers. Ordinary branch divergence, dirty state, untracked versionable files, generated projections, lint/format failures, and other repairable pending work are not blockers: repair them within the selected worktree and continue under the same authorization.
+Every product commit requires causal Task/Change/Execution records and matching write scopes. Only `.agents/records/**` and `.local/**` changes are exempt. Conversation capture alone does not authorize a product commit; never borrow the latest global Task. See [commit policy](../zaip-skill-task/references/commit-policy.md).
 
-## Prove folder-scoped SSH first
+## Qualify the exact candidate and deliver
 
-From the repository root, read `.agents/config/project.yaml` immediately before deployment. Resolve `deploy.branch`; use `main` only when the file or key is absent. A malformed existing file or invalid branch is a terminal preflight failure. Never infer a target from the checked-out or upstream branch. Select the requested remote (default `origin`), then run once:
+1. Compose `$zaip-skill-release-qualification` and follow [local preparation](../zaip-skill-release-qualification/references/local-preparation.md). Synchronize and commit before preparing the clean exact SHA. Failed or stale evidence is not qualification.
+2. Resolve the previous Release, next canonical version and package identity using [release identity](references/release-identity.md). For the framework, `vN.N` maps to package `N.N.0`; only GitHub Actions publishes `@zaip-ai/cli` to npm.
+3. For `zaip-ai/zaip-aios`, use `scripts/local-release-deploy.mjs`. It prepares/verifies, pushes the exact SHA to configured `main`, uploads verified assets to a draft, then publishes the Release. Enable the thin publisher only after explicit rollout authority, public trust enrollment and signed full local qualification. It validates published assets and runs one read-only installation smoke before npm; no private-draft pilot or write token is needed. GitHub Release publication and npm completion remain separate.
+4. Consumers use `scripts/consumer-release-preparation.mjs guarded-push` with their own policy and explicit branch, SHA and trusted receipt. They have no framework npm/TGZ requirement. See the preparation guide for bootstrap and guarded commands.
+5. Immediately before delivery, reread the configured target; if changed, restart preparation. Helpers bind the exact candidate to `HEAD:refs/heads/<configured branch>` (or its equivalent immutable-SHA refspec); do not bypass them with a manual push.
+6. After qualification, a missing Release is normal. Unless explicitly push-only, automatically create the draft for that SHA or resume a verified draft for the same SHA. Verify an already-published exact Release as a no-op; an API/authentication error never proves absence. Refuse conflicting tags/assets without overwrite.
+7. Review complete categorized UTF-8 notes and their exact-range inventory under [release notes](references/release-notes.md). Never use `--generate-notes` as the Release body. Validate the notes, publish with the reviewed notes file, and compare the published body byte-for-byte on readback. Preserve a configured human-only review policy where applicable.
 
-```powershell
-node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin
-```
+## Proportional validation
 
-The preflight must prove that the push URL uses SSH, no process override is active, the effective `core.sshCommand` comes from repository-local or matching folder configuration, its private key exists, Git identity exists, and `git ls-remote` succeeds.
+Guarded local framework delivery requires a valid `full-v2` receipt with the mandatory full gate.
+Without explicit thin-path activation, the default GitHub publisher separately requires the legacy workflow's
+exact-candidate qualification receipt after its full gate and TGZ matrix.
+Rapid impact checks have no test-count ceiling and cannot substitute for release evidence.
+Use the budgets and failure rules in [local preparation](../zaip-skill-release-qualification/references/local-preparation.md).
+Consumer projects retain their own reviewed policy commands. Report qualification and
+publication separately; neither preparation nor this policy grants publication authority.
 
-Run preflight once at the start of the authorized deployment. On failure, stop. Do not edit Git/SSH configuration, use `git -c core.sshCommand=...`, set an environment override, or invoke `ssh -i` directly. Retain the sanitized result as evidence.
+## Verify and close
 
-## Review and validate
+- After push, compare the local SHA with the configured remote ref. If the push result is uncertain, read remote state first; only one documented transient transport retry is allowed per cycle.
+- Observe required GitHub checks for that exact SHA, waiting up to 20 minutes with concise progress at least once per minute. Read the exact failed step before repairing. Never repeat an unchanged failing command or disable a gate for green status.
+- Reconcile recoverable prerequisites and continue through the same bounded repair policy; do not stop merely because a Release or generated file was absent.
+- Success requires matching local/remote hashes, successful required observable checks, verified Release identity/body and a clean intended worktree. Distinguish GitHub publication, npm availability and formal lifecycle closure. If checks cannot be observed, report CI as unconfirmed.
+- Retain terminal evidence and close every owned Task/Change/Execution correctly through the finalizer. Never finish with an owned Task executing/verifying; use completed, blocked, cancelled or failed according to observed outcome.
 
-1. Snapshot `git status --short --branch`, file names, and the diff summary.
-2. Inspect suspicious environment, key, certificate, state, or credential files without printing secret values. Block secrets and files at or above GitHub's 100 MB limit.
-3. Reuse valid evidence for unchanged work. Run only gates required by repository Rules, the active Change, or the failed GitHub job.
-   - Turbo cache hits are valid only when the active work did not originate from a failed remote CI gate.
-   - When repairing failed CI, reproduce the exact failed gate once per repair cycle with Turbo cache bypassed when applicable.
-4. If a local gate fails, capture the exact failing command and error, make the smallest authorized repair, update lifecycle evidence, and start the next cycle without asking for another deploy authorization.
-5. After all required local gates pass, stage each reviewed selected-worktree path with `git add -- <explicit-pathspecs>`. If a file is secret, oversized, ignored by policy, or outside the selected worktree, exclude it and report the reason; otherwise include it.
-
-## Synchronize and publish each cycle
-
-Fetch the selected remote and configured branch once per publication cycle, without SSH overrides. Compute ahead/behind against `<selected remote>/<configured branch>`. When local is behind or diverged, apply the recorded bounded reconciliation strategy and continue after successful verification; stop only if it cannot be completed safely within the bounded repair cycles. Never reset or force.
-
-Commits created during Task execution use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`: the effective executing-agent prefix followed by compact lineage.
-
-- Codex: `[CODEX] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`
-- Claude: `[CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`
-
-The effective provider is exclusively `CODEX` or `CLAUDE`; `AUTO` is not part of a Task subject. P/S/T blocks are emitted only when their evidence exists; a Task with no PRD or SPEC uses `[Task-first:XXXX]`, and an unattributed functional commit uses `[CODEX] <functional title>` without `ZAIP-Task`. The subject remains ≤96 characters and only its title may truncate at a word boundary. Complete available PRD, SPEC, Task, Change, and Execution IDs remain in `ZAIP-*` trailers. An explicit deploy may create only its evidenced functional commits, without broad staging, force, destructive reset, or squashing.
-
-Immediately before push, re-read the target with `node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --resolve-branch`. If it changed since preflight, restart validation and synchronization for the new target. Push once per publication cycle with the explicit configured refspec: `git push <remote> HEAD:refs/heads/<configured branch>`. Do not use a bare `git push` or infer a target from upstream. If there is no unpushed commit after the bounded reconciliation and functional-commit review, report a no-op.
-
-- If push fails, treat it as terminal unless repository content caused a documented server-side rejection that can be repaired locally.
-- Never switch keys, accounts, remotes, or transport, and never pass SSH/config overrides or force options.
-
-## Verify and monitor GitHub checks
-
-1. After every push, compare `git rev-parse HEAD` with one `git ls-remote <remote> refs/heads/<configured branch>` result.
-2. Inspect required GitHub checks for that exact commit using an available authenticated GitHub CLI, API, connector, or browser session. Wait up to 20 minutes for terminal status and provide a concise progress update at least once per minute.
-3. If all required checks pass, confirm the remote hash, commit title, SSH identity source, key path, and worktree status.
-4. If a check fails, read the exact job and step logs before editing. Do not weaken or remove the check merely to obtain green status.
-5. Repair the evidenced cause, complete lifecycle records, and start the next cycle under the same user authorization.
-6. If checks cannot be observed, report the push as successful but CI as unconfirmed; never claim the deployment is fully validated.
-
-## Success condition
-
-Finish only when the local and remote hashes match, every required observable check is successful, and the intended worktree is clean. Otherwise report the exact terminal blocker and the repair cycles consumed.
+Database request-branch PRs retain their separate policy. This Git-only skill never applies SQL, provisions paid resources or publishes database production. Read-only identities cannot substitute for deploy credentials.

package/templates/.agents/skills/zaip-skill-github-deploy/references/deployment-workflow.md

@@ -0,0 +1,135 @@
+
+# Deploy and repair GitHub publication
+
+The exact command “faça deploy” authorizes publication of everything versionable in the selected worktree, including tracked and untracked files, after the safety gates below. It does not authorize provider deployment.
+
+Treat deploy as Git-only publication. An explicit current-turn request to `deploy`, `push`, `publicar`, `publicação` or GitHub publication selects this skill; it authorizes only the bounded Git publication described below, never a provider deployment or automatic publication.
+
+## Authorization
+
+- Require an explicit deploy, push, publicar, publicação, GitHub publication, or failed-deploy repair request in the current turn.
+- The request authorizes the initial publication, automatic reconciliation needed to publish the selected branch, commits covering all versionable pending changes in the selected worktree, and up to five repair cycles needed to make required local and remote GitHub checks pass. Do not stop merely because the worktree is dirty, history is behind/diverged, generated files are pending, or a local gate has a repairable failure.
+- Limit repairs to the intended repository state and the evidenced failure. Do not add unrelated features or broaden product scope.
+- Never force push, rewrite history, replace remotes, change credentials or Git/SSH configuration, bypass checks, or deploy to another service.
+- Do not create lifecycle artifacts for an explicit Git-only publication request. The deploy authorization permits staging every inventoried versionable path in the selected worktree after secret, size, and ignore checks; it never authorizes changes outside that worktree.
+- Every product commit needs its evidenced Task and canonical Task title, including Task-first. If ownership is missing, materialize the authorized work before editing/committing; never borrow the latest global Task. Only records/local-only snapshots are exempt. Omit nonexistent PRD/SPEC lineage. Explicit deploy authorizes reviewed path staging, never force, destructive reset, history rewrite, or credential changes.
+
+## Mandatory authorization record
+
+Before the first Git mutation, retain a sanitized authorization record in the task's visible progress and terminal report. It must state:
+
+1. the user's current-turn publication intent;
+2. repository, remote, branch and selected worktree;
+3. whether the grant is simple push or partitioned commit plus push;
+4. the bounded history-reconciliation strategy (`rebase` by default, or user-selected `merge`);
+5. allowed repair cycles, excluded worktrees/scopes and prohibited actions;
+6. the preflight result and the recoverable preservation reference used before reconciliation.
+
+For publication of existing commits, the conversation and terminal deploy report are the authority record; no artificial Task is needed. New product edits or commits require Task ownership under the workflow and commit policy. Never store credentials, private-key contents, tokens or environment values. Request only authority actually missing from the current request.
+
+## Multiple worktrees and divergent history
+
+1. Resolve the selected publishing worktree and inspect its `git status --porcelain`; use `git worktree list --porcelain` only to detect a path collision, never to scan every worktree.
+2. Select exactly one publishing worktree. A clean worktree on another branch or a detached verification worktree does not join the deploy. The selected worktree is the complete publication scope.
+3. Report a detected path collision, but do not block solely because the selected worktree is dirty or contains mixed changes; the explicit “faça deploy” authorization includes those changes. Stop only for an unresolved index conflict, secret/oversize file, authentication failure, or destructive/rewrite requirement.
+4. Prunable or missing worktrees are reported but never pruned automatically. Dirty detached or temporary worktrees are never deleted, reset, stashed or copied into the publishing worktree implicitly.
+5. Fetch once and compute ahead/behind for the publishing branch. If it is behind or diverged, automatically reconcile only the selected branch under this deploy authorization and continue; divergence is not a blocker by itself.
+6. Before reconciliation, create a recoverable branch reference and preserve tracked plus untracked changes in a named stash. Verify both references before proceeding. Use `rebase` unless the user explicitly selected `merge`.
+7. Apply the bounded reconciliation without force. Restore with `git stash apply`, retain the stash until publication succeeds, and resolve generated aggregate conflicts by regenerating them from canonical sources. For ordinary textual conflicts, combine both sides when safe; use the selected worktree's intended version only when the diff and commit history establish that it supersedes the remote version.
+8. After restoration, prove that no unmerged paths remain, re-inventory the diff, and only then begin functional partitioning. Continue automatically through recoverable conflicts and pending repairs; stop only for a genuine terminal blocker defined below.
+
+## Repair-loop integrity
+
+- A publication cycle is: run deploy preflight, inventory the intended pending diff, synchronize, create any required functional commits with explicit pathspecs, push, and verify the remote hash. When no intended pending diff exists, publish already-formed commits. Run only gates required or evidenced by repository Rules, the active Change, or failed remote CI.
+- Inventory the complete pending diff, run the safety gates, then stage the reviewed inventory with `git add -- <explicit-pathspecs>` and commit it. Generate pathspecs from the reviewed tracked and untracked inventory; do not use `git add -A`, broad globs, or paths outside the selected worktree. Do not require functional partitioning for this explicit broad-deploy mode.
+- Run each diagnostic, gate, fetch, stage, commit, push, and hash verification at most once per cycle, except the single documented transient push retry below.
+- Start a new cycle only after a repository change or new remote evidence. Never repeat an unchanged failing command hoping for a different result.
+- Continue until all required checks pass or a terminal blocker occurs. Stop after five repair cycles, or when the same root cause remains after two repairs.
+- Treat authentication, unavailable credentials, unresolved conflicts after bounded repair, secret exposure, destructive changes, GitHub outages, and ambiguous scope expansion as terminal blockers. Ordinary branch divergence, dirty state, untracked versionable files, generated projections, lint/format failures, and other repairable pending work are not blockers: repair them within the selected worktree and continue under the same authorization.
+
+## Prove folder-scoped SSH first
+
+From the repository root, read `.agents/config/project.yaml` immediately before deployment. `deploy.frontend.branch` and `deploy.backend.branch` are persistent authorization and may be `main`; pass their explicit `--scope`. `deploy.database.branch` is literal `beta`, never falls back to `main`, and requires `--scope database`. The internal `--scope framework` and a legacy preflight without `--scope` use `deploy.branch`, which must remain non-production. A malformed config is a terminal preflight failure. Preflight never creates, renames, or switches a branch.
+
+For a database migration request, the database worktree may push only `HEAD:refs/heads/request/<id>` to open its PR against `beta`. That route never targets `main`, never applies SQL, and does not provision a beta branch or Supabase resource.
+
+```powershell
+node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin
+```
+
+The preflight must prove that the push URL uses SSH, no process override is active, the effective `core.sshCommand` comes from repository-local or matching folder configuration, its private key exists, Git identity exists, and `git ls-remote` succeeds.
+
+Run preflight once at the start of the authorized deployment. Classify a failure before stopping: authentication, SSH configuration, unavailable authority, or an external access failure is a terminal blocker; an evidenced repository-content or missing-prerequisite failure within the authorized scope may be repaired in the bounded cycle and then rechecked. Do not edit Git/SSH configuration, use `git -c core.sshCommand=...`, set an environment override, or invoke `ssh -i` directly. Retain the sanitized result as evidence.
+
+## Environment and access contract
+
+- `READ-ONLY-BETA` and `READ-ONLY-PROD` are explicit query-only identities. They must have separate credentials and targets, remain unable to apply migrations, mutate backend data, change provider settings, or publish Git refs, and must never be substituted for a deploy credential.
+- Database automation publishes only the literal `beta` branch through reviewed migration PRs. Backend follows `deploy.backend.branch`, including `main` when configured. Database production promotion remains a human GitHub merge after review and required checks.
+- Frontend and site can publish their own validation builds from the configured validation branch. Their provider configuration remains project-owned and separate from production; this Git-only skill does not authorize a provider deployment.
+- A central database repository is optional and configured by the consuming project. Do not infer a repository name, remote, service target, or credential from another repository.
+
+## Validation budget
+
+Guarded local framework preparation requires `full-v2` and its mandatory full gate.
+The default legacy GitHub publisher accepts its separate exact-candidate qualification
+receipt only after the remote full gate and TGZ matrix. Explicit administrator activation after signed full local qualification switches the
+publisher to the verified local receipt. One read-only install smoke then gates npm;
+no private-draft pilot is required. Activation is never implicit.
+Follow [local preparation](../../zaip-skill-release-qualification/references/local-preparation.md)
+for exact-candidate evidence, deadlines and rapid-preparation limits. Impact selection has
+no test-count ceiling; rapid results are not release receipts. Preserve consumer policy
+boundaries and reuse only valid matching evidence. On timeout, terminate the command tree,
+retain the failed gate and repair its evidenced cause; never omit gates to obtain success.
+
+## Review and validate
+
+1. Snapshot `git status --short --branch`, file names, and the diff summary.
+2. Inspect suspicious environment, key, certificate, state, or credential files without printing secret values. Block secrets and files at or above GitHub's 100 MB limit.
+3. Reuse valid evidence for unchanged work. Run only gates required by repository Rules, the active Change, or the failed GitHub job.
+   - Turbo cache hits are valid only when the active work did not originate from a failed remote CI gate.
+   - When repairing failed CI, reproduce the exact failed gate once per repair cycle with Turbo cache bypassed when applicable.
+4. If a local gate fails, capture the exact failing command and error, make the smallest authorized repair, update lifecycle evidence, and start the next cycle without asking for another deploy authorization.
+5. After all required local gates pass, stage each reviewed selected-worktree path with `git add -- <explicit-pathspecs>`. If a file is secret, oversized, ignored by policy, or outside the selected worktree, exclude it and report the reason; otherwise include it.
+
+## Consumer release preparation
+
+Every authorized deploy must first compose `$zaip-skill-release-qualification` and use its guarded delivery entrypoint. Complete synchronization and commits before preparing the exact clean candidate. See [the executable preparation guide](../../zaip-skill-release-qualification/references/local-preparation.md). A prose review or an unsigned test result does not replace preparation.
+
+For `zaip-ai/zaip-aios` framework releases, use `scripts/local-release-deploy.mjs`: it prepares and verifies the candidate, pushes the exact SHA to `main`, uploads the verified assets to a draft release, and publishes that release. npm publication remains exclusively in GitHub Actions. Run the folder-scoped SSH preflight with the explicitly configured frontend scope before this entrypoint.
+
+After exact-candidate qualification, a missing GitHub Release is normal. Unless the request is explicitly push-only, use the configured entrypoint to create a draft for that SHA or resume a verified draft for the same SHA; do not recreate an existing Release. A published Release for the exact SHA is verified as a no-op, or its failed checks are repaired within the bounded cycle. An authentication or API error does not prove that a Release is absent.
+
+For a consumer repository, bootstrap its own Ed25519 trust store and define `configured_branch`, GitHub version `vN.N`, and `required_commands` in its project policy. `prepare` runs only those policy commands and signs a receipt after the Git identity is unchanged before and after them. `verify` checks the configured branch, exact SHA/tree, policy digest and trusted key. `guarded-push` runs prepare and verify before its explicit push command; a failed required command, dirty checkout, changed SHA/policy, or unavailable key prevents that command from running. This consumer flow is GitHub-only: it has no npm channel, package manifest version, or TGZ contract.
+
+## Synchronize and publish each cycle
+
+Fetch the selected remote and configured branch once per publication cycle, without SSH overrides. Compute ahead/behind against `<selected remote>/<configured branch>`. When local is behind or diverged, apply the recorded bounded reconciliation strategy and continue after successful verification; stop only if it cannot be completed safely within the bounded repair cycles. Never reset or force.
+
+Commits created during Task execution use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`: the effective executing-agent prefix followed by compact lineage.
+
+- Codex: `[CODEX] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`
+- Claude: `[CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`
+
+The effective provider is `CODEX` or `CLAUDE`. P/S/T blocks require evidence; standalone Tasks use `[Task-first:XXXX]` followed by their canonical title. The subject remains ≤96 characters with title truncation at word boundaries; full IDs remain in `ZAIP-*` trailers. All product commits require a real Task, matching causal records and write scopes. Only `.agents/records/**` and `.local/**` changes are exempt; conversation capture does not authorize commits. Run `commit validate` and preserve the installed `commit-msg` hook. See `docs/task-commit-policy.md`. Explicit deploy never authorizes broad staging, force, destructive reset or squashing.
+
+Immediately before delivery, re-read the configured target with preflight and the explicit scope. If it changed, restart preparation for the new target. Consumer frontend/backend publication must use `consumer-release-preparation.mjs guarded-push`; framework publication must use `scripts/local-release-deploy.mjs`. These entrypoints bind preparation to the exact SHA and explicit branch refspec. Do not bypass them with a manual push. The separately authorized database request-branch PR route retains its database-specific gates and is outside these release helpers. A default deploy completes the Release flow; only an explicit push-only request stops after the push. If there is no unpushed commit or pending release after reconciliation and review, report a no-op.
+
+- If a push result is uncertain, read the remote state before acting. Reconcile a non-fast-forward through the existing bounded policy; retry one documented transient server or transport failure per cycle. Authentication, authorization, configuration, or other external-access failures are terminal blockers.
+- Never switch keys, accounts, remotes, or transport, and never pass SSH/config overrides or force options.
+
+## Verify and monitor GitHub checks
+
+1. After every push, compare `git rev-parse HEAD` with one `git ls-remote <remote> refs/heads/<configured branch>` result.
+2. Inspect required GitHub checks for that exact commit using an available authenticated GitHub CLI, API, connector, or browser session. Wait up to 20 minutes for terminal status and provide a concise progress update at least once per minute.
+3. If all required checks pass, confirm the remote hash, commit title, SSH identity source, key path, and worktree status.
+4. If a check fails, read the exact job and step logs before editing. Do not weaken or remove the check merely to obtain green status.
+5. Repair the evidenced cause, complete lifecycle records, and start the next cycle under the same user authorization.
+6. If checks cannot be observed, report the push as successful but CI as unconfirmed; never claim the deployment is fully validated.
+
+## Release identity
+
+Unless the request is push-only, resolve the release identity before mutation using the verified candidate SHA and tag list. Follow [the release identity contract](release-identity.md): consumer GitHub releases stay independent; framework `vN.N` maps to package `N.N.0`, and only qualified GitHub Actions can publish `@zaip-ai/cli` to npm.
+
+## Success condition
+
+Finish only when the local and remote hashes match, every required observable check is successful, and the intended worktree is clean. Otherwise report the exact terminal blocker and the repair cycles consumed.

package/templates/.agents/skills/zaip-skill-github-deploy/references/github-release-workflow-template.md

@@ -0,0 +1,31 @@
+# Configure GitHub-only validation once
+
+Run from the consumer project's root after selecting its actual validation commands:
+
+```sh
+node .agents/skills/zaip-skill-github-deploy/scripts/install-github-readiness-workflow.mjs --repository owner/repo --checks-json '["validate"]' --commands-json '["npm run lint","npm test","npm run build"]'
+```
+
+Use only commands the project defines. The generated workflow has one aggregate job named by the single `--checks-json` entry; all commands must succeed. Do not list step names as required jobs. Existing custom workflows may have multiple required jobs and can use the readiness command without running setup.
+
+Setup detects `package-lock.json` or `pnpm-lock.yaml`, pins Node 22 by default, configures the matching dependency cache, installs dependencies once, then runs the selected commands. Override the application's runtime with `--node-version 24` when appropriate. pnpm uses the exact version in `package.json#packageManager`, or an explicit `--pnpm-version N.N.N`. Multiple lockfiles require an explicit `--package-manager npm|pnpm`.
+
+For another stack, use `--package-manager none` and supply its environment setup and validation commands. This mode adds no Node dependency setup or cache. Node projects without lockfiles require explicit custom setup instead of a guessed installation command.
+
+The default destination is `.github/workflows/zaip-github-release.yml`. A custom `--output` must stay inside this project's `.github/workflows`. Identical reruns return `changed: false`; a different existing file, symlink or symlinked parent is refused. Review the generated diff and commit it with the lockfile. npm installation of ZAIP only distributes these helpers; it never rewrites a project's workflows automatically.
+
+# Deploy using the completed checks
+
+The workflow runs on push, pull request or manual dispatch, uses read-only repository permission and cancels obsolete checks for the same ref. It does not create a release or publish npm packages.
+
+After it completes, query GitHub from outside that workflow:
+
+```sh
+node .agents/skills/zaip-skill-github-deploy/scripts/github-readiness.mjs --repository owner/repo --sha <exact-40-character-sha> --checks-json '["validate"]'
+```
+
+Provide `GITHUB_TOKEN` through the environment with repository/Actions read access. Never put credentials in the command, generated file or logs. If using an existing custom workflow, also pass `--workflow-path .github/workflows/custom.yml` and its actual required job names.
+
+The command queries the latest matching run and its exact attempt's jobs, including additional pages. It emits JSON and exits nonzero when required evidence is missing, pending, failed or belongs to another origin. Do not put this command inside the same workflow it waits to complete.
+
+Only after readiness succeeds, use `resolve-release-identity.mjs` and the skill's guarded GitHub Release flow: initial `v1.0`, numeric minor increments, exact tag/SHA binding and validation prerelease metadata. Reuse matching evidence and tags on retry; changes to the candidate require new checks. This process does not publish npm packages.

package/templates/.agents/skills/zaip-skill-github-deploy/references/release-gate-matrix.md

@@ -0,0 +1,24 @@
+# Release gate retention matrix
+
+| Gate | Qualification location | Publication cost |
+|---|---|---|
+| Architecture, CQRS, modules, profile, skills, tools, encoding, source size, lint, types and contracts | `prepare-and-qualify`: `validate:github:prepared` | None; reuse successful run for the same SHA |
+| Dashboard and Design workspace unit tests | `validate:github:prepared`, separately from package coverage | None |
+| `packages/**` unit coverage and ratchet | `create-coverage-qualification.mjs`, once | None |
+| Public CLI units, integration and installer profiles | `test:qualification:prepared` | None |
+| Release cleanroom, rollback, supply chain and client contracts | `test:release-e2e:prepared` and source validation | None |
+| Production dependency audit | `pnpm audit --prod --audit-level high` | None |
+| Dashboard and Design browser checks | Dashboard E2E workspace | None |
+| Linux, Windows and macOS Node 22; Linux Node 24 | `exact-tgz-smoke`, SHA-256 checked TGZ, install and doctor | None |
+| Literal consumer record identity through SQLite, API and UI | `consumer-identity --tarball` with the same TGZ | None |
+| Package build, template sync and pack | Prepared once before artifact fan-out | No build or pack |
+| Repository, workflow, SHA, latest run attempt, policy, expiration and artifact digests | Receipt created after all gates; GitHub API checked again by publisher | Small verification steps |
+| GitHub release tag and npm registry integrity | `publish-cli.yml` | Required publication checks plus exact registry-version smoke |
+
+`qualify-cli.yml` starts automatically on pushes to the configured validation or human-promoted production branch. A manual dispatch requires that branch head to equal the input SHA. A changed SHA requires a new qualification. Workflow run IDs and attempts identify evidence; a local receipt alone is never authority.
+
+Publication uses an unexpired successful qualification (maximum seven days). It downloads the qualified artifact; it never invokes `release:artifacts`, `npm pack`, coverage, browser qualification or a broad agent review. Missing, altered, expired or failed qualification blocks publication.
+
+A GitHub prerelease publishes to `beta`; a production Release after human promotion publishes to `latest`. Only the framework release workflow publishes npm. Consumer installations receive the single GitHub skill and its GitHub-only setup helpers.
+
+Measure qualification and publication separately in GitHub Actions after rollout. No wall-clock improvement is claimed from local tests alone.

package/templates/.agents/skills/zaip-skill-github-deploy/references/release-identity.md

@@ -0,0 +1,44 @@
+# Release identity contract
+
+Use the helper before a GitHub Release decision. It accepts a verified candidate SHA and either a verified tag list or an explicit canonical product version:
+
+```powershell
+node .agents/skills/zaip-skill-github-deploy/scripts/resolve-release-identity.mjs --sha <sha> --channel <validation|production> --tags-json <verified-json>
+node .agents/skills/zaip-skill-github-deploy/scripts/resolve-release-identity.mjs --sha <sha> --channel <validation|production> --version <N.N>
+```
+
+- Product tags use canonical `vN.N`: begin at `v1.0`, increment the numeric minor by default, and change major only on an explicit request. The helper selects the numeric maximum across verified tags, including prereleases.
+- A retry may reuse a tag only when it belongs to the exact candidate SHA. Never move, delete, or recreate a tag.
+- Create a validation release only after preparing and validating the reviewed Markdown body required by the [release-notes contract](release-notes.md): `gh release create <tag> --repo <owner/repo> --target <sha> --title <title> --notes-file <reviewed-notes.md> --prerelease --latest=false`. Never use `--generate-notes`; a compare link alone does not describe a release. Read the published body back with `gh release view <tag> --repo <owner/repo> --json body` and validate it against the same inventory before declaring success. Production is human-promoted, has a new SHA, and must qualify and version again.
+- Record the product version, tag, exact SHA, channel, prerelease flag, and GitHub Release URL. GitHub checks, registry integrity, smoke, and lifecycle closure remain separate evidence.
+
+## Deterministic recovery
+
+Resolve the candidate identity before any release mutation. A missing Release after exact-candidate qualification is normal: for a default deploy, create a new draft for the candidate SHA or resume an existing verified draft for that SHA. A published Release on that exact SHA must be verified as a no-op; retry only its observed failed CI within the bounded repair policy, never recreate the Release.
+
+If the intended tag resolves to another SHA, never move, delete, or recreate it. For a consumer, select the next allowed minor under its release policy, then prepare its new exact candidate. For the framework, select the next allowed minor, update all required package manifests, commit the version change, and prepare and qualify the resulting candidate on its configured release branch. A changed candidate never inherits its predecessor's qualification.
+
+For a missing or expired receipt, use the candidate's configured preparation mechanism: a consumer runs its existing local `prepare` and `verify`; the framework uses its local release helper and receipt; a legacy remote qualification workflow runs only where the configured pipeline requires it, on the exact candidate SHA, branch, and channel. Observe a pending run; repair an observed failure under the existing limit of five cycles, stopping when the same cause remains after two repairs. Authentication, authorization, transport, or API failures do not establish that a Release, tag, receipt, or workflow run is absent; report them as access blockers. Keep exact-SHA readiness gates, protected trust rules, and human-only production promotion intact. A push-only request creates no Release; otherwise the deploy completes the Release flow.
+
+For a first release, prepare the missing local notes and inventory in initial mode and validate them with `--initial`; absence of a prior tag is not a blocker.
+
+## Framework package contract
+
+Consumer repositories remain GitHub-only and independent. Recognize the framework source only when the approved `origin` is `zaip-ai/zaip-aios`, the root package is `@zaip-ai/aios` and `public-cli/packages/cli/package.json` identifies `@zaip-ai/cli`. Read the versions from the root, `public-cli/package.json` and CLI package manifests; require the same canonical `N.N.0` version, then call the helper with explicit `--version N.N`. Never allocate an independent GitHub version in this repository. A version change must update the declared package metadata before the candidate is committed and qualified; do not replace version strings broadly.
+
+Publishing a GitHub Release in this framework triggers its npm workflow. Report this consequence in the GitHub publication scope and follow the configured pipeline through terminal status; no second npm skill or local publication step is needed. A push-only request does not create a Release or publish npm. A successful GitHub Release with failed/unobserved npm checks is a partial result.
+
+`qualify-cli.yml` runs on pushes to the configured validation (`beta` npm channel) and human-promoted
+production (`latest` npm channel) branches. It qualifies the exact SHA and uploads one tested TGZ plus
+a receipt. Other branch pushes do not qualify a release. For an authorized manual qualification retry,
+dispatch that workflow on the candidate's configured branch with its exact current head `sha` and
+matching `npm_channel`. Qualification is read-only; it does not publish npm or create a Release.
+
+Before creating or resuming a draft Release, require the installed `github-readiness.mjs` command with `--repository zaip-ai/zaip-aios --sha <sha> --branch <configured-release-branch> --workflow-path .github/workflows/qualify-cli.yml --checks-json '["receipt"]'` to report ready.
+The publisher independently checks the latest qualifying run and attempt, workflow path, repository,
+SHA, channel, receipt lifetime and artifact digests. It waits for a pending qualification, refuses a
+failed or missing one, and consumes the approved TGZ without repeating source tests or builds.
+Receipts expire after seven days; a changed candidate requires new qualification. Preserve required
+GitHub checks and investigate their failures, rather than replacing passing evidence with another AI review.
+
+Only the qualified GitHub Actions workflow may publish `@zaip-ai/cli` to npm. Never run `npm publish`, `pnpm publish`, or an equivalent local publication command. The workflow must bind the publication to the exact qualified SHA, tag, package version, and artifact digest.