@zaip-ai/cli 0.1.0 → 1.0.1

package/templates/.zaip-aios/templates/skills/zaip-skill-frontend-launcher/references/launcher-contract.md

@@ -0,0 +1,36 @@
+# Contrato do launcher local
+
+## Estrutura
+
+- `<surface>/launcher.exe`: artefato de duplo clique.
+- `<surface>/packages/windows-launcher/`: fonte C# e build PowerShell.
+- `<surface>/packages/local-runtime/`: servidor loopback, sessão, lock e testes.
+- `<surface>/apps/frontend/dist/`: build estático servido; ajuste o path à superfície real.
+
+## Invariantes
+
+- Defina uma única fonte visual canônica; em workspaces ZAIP use por padrão
+  `.agents/config/src/icon_zaip.png`, salvo override explícito do projeto.
+- Aceite fonte PNG ou ICO. PNG deve ser quadrado, medir entre 16 e 256 px e ser convertido em ICO
+  temporário durante o build; recomende 256×256 para novos assets.
+- Compile `winexe` com `/win32icon` e remova o ICO temporário. Nunca dependa do ícone genérico do
+  sistema nem mantenha uma cópia derivada que possa divergir da fonte.
+- Bind somente em `127.0.0.1`; nunca exponha em `0.0.0.0`.
+- Use health endpoint exclusivo com `kind` e hash estável do workspace.
+- Grave `workspace`, `workspaceKey`, `rootPid`, `port` e `createdAt` no diretório temporário.
+- Crie lock por operação atômica de filesystem, com timeout e recuperação de lock obsoleto.
+- Dentro do lock, valide a sessão e procure health compatível na faixa limitada antes de iniciar.
+- Não considere uma porta ocupada como runtime próprio sem validar o marcador e o workspace.
+- Sirva somente arquivos dentro do build root, rejeitando URL malformada e path traversal.
+- Abra o navegador apenas após listen e sessão persistida; rotas hash podem ser abertas diretamente.
+- O wrapper `winexe` deve encerrar após disparar Node oculto; o runtime é dono do servidor.
+
+## Evidência mínima
+
+1. O ícone extraído do executável existe, corresponde visualmente à fonte canônica e não é o ícone
+   genérico.
+2. Testes do servidor e do boundary de arquivos passam.
+3. Uma porta preferencial ocupada por outro processo é ignorada sem encerrá-lo.
+4. Dois disparos do executável mantêm o mesmo `rootPid` e a mesma `port`.
+5. Existe somente um processo do runtime para o workspace.
+6. O artefato distribuído funciona em path com espaços e em instalação limpa.

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

@@ -0,0 +1,75 @@
+---
+name: zaip-skill-github-deploy
+description: Use only when the user explicitly asks to publish to GitHub with folder-scoped SSH or repair a failed publication in bounded cycles; the policy-authorized demo branch may activate it automatically.
+---
+
+# Deploy and repair GitHub publication
+
+Treat deploy as Git-only publication. Provider deployment is separate and requires explicit authorization.
+
+## Authorization
+
+- Require an explicit deploy, push, publication, or failed-deploy repair request in the current conversation, unless the current branch is `demo` and the project configuration explicitly grants standing automatic deployment for that branch.
+- The request authorizes the initial publication and up to five repair cycles needed to make required local and remote GitHub checks pass.
+- 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. A pure deploy/push only performs the deploy preflight, stages/commits the requested pending files, pushes, and verifies the remote hash. If the request also asks to repair code or CI, that repair is separate work and may use the normal ZAIP lifecycle.
+
+## Repair-loop integrity
+
+- A pure publication cycle is: run deploy preflight, stage, synchronize, commit, push, and verify the remote hash. Do not run project tests, builds, lint, or GitHub checks as part of deploy unless the user explicitly requests validation or a separate repair is in scope.
+- 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, branch divergence, secret exposure, destructive changes, GitHub outages, and ambiguous scope expansion as terminal blockers.
+
+## Prove folder-scoped SSH first
+
+From the repository root, select the explicit remote or `origin`, then run once:
+
+```powershell
+node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin --branch demo
+```
+
+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. 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.
+
+## 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 local gates pass, run `git add -A` once for that publication cycle. Inspect `git diff --cached --name-status`, `git diff --cached --stat`, and `git diff --cached --check`. Never force-add ignored files.
+
+## Synchronize and publish each cycle
+
+Fetch the selected remote and current branch once per publication cycle, without SSH overrides. Compute ahead/behind against the fetched ref. Stop when local is behind or diverged; do not merge, rebase, reset, or force.
+
+Use the executing-agent commit prefix:
+
+- Codex: `[AUTO][CODEX]`
+- Claude: `[AUTO][CLAUDE]`
+- Gemini: `[AUTO][GEMINI]`
+- Roo: `[AUTO][ROO][15 AGENTS]`
+
+Commit once and push once per publication cycle. With an upstream, use `git push`; for first publication, use `git push -u <remote> <branch>`. If the index is empty and there is no unpushed commit, 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/<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.

package/templates/.zaip-aios/templates/skills/zaip-skill-github-deploy/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "ZAIP GitHub Deploy"
+  short_description: "Deploy GitHub com reparos controlados"
+  default_prompt: "Use $zaip-skill-github-deploy para publicar este repositório via SSH da pasta, corrigindo falhas locais ou do CI em ciclos controlados até os checks passarem."
+policy:
+  allow_implicit_invocation: true

package/templates/.zaip-aios/templates/skills/zaip-skill-github-deploy/scripts/preflight.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+const options = parseArguments(process.argv.slice(2));
+
+try {
+  const requestedRepository = resolve(options.repository);
+  const repository = git(requestedRepository, ["rev-parse", "--show-toplevel"]).trim();
+  const gitDirectory = git(repository, ["rev-parse", "--absolute-git-dir"]).trim();
+  const branch = git(repository, ["branch", "--show-current"]).trim();
+  if (branch === "") fail("detached HEAD is not deployable");
+  if (options.branch !== null && branch !== options.branch) {
+    fail(`current branch ${branch} does not match required branch ${options.branch}`);
+  }
+
+  for (const variable of ["GIT_SSH", "GIT_SSH_COMMAND"]) {
+    if (process.env[variable]?.trim()) fail(`${variable} overrides folder-scoped Git SSH config`);
+  }
+
+  const pushUrl = git(repository, ["remote", "get-url", "--push", options.remote]).trim();
+  if (!isSshUrl(pushUrl)) fail(`remote ${options.remote} push URL is not SSH: ${pushUrl}`);
+
+  const name = requiredConfig(repository, "user.name");
+  const email = requiredConfig(repository, "user.email");
+  const sshCommand = requiredConfig(repository, "core.sshCommand");
+  const sshSource = configPath(sshCommand.origin, repository);
+  if (!isFolderScoped(repository, gitDirectory, sshSource)) {
+    fail(
+      `core.sshCommand is not repository-local or loaded by a matching includeIf gitdir: ${sshCommand.origin}`,
+    );
+  }
+
+  const identityArgument = /(?:^|\s)-i(?:\s+|=)(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(
+    sshCommand.value,
+  );
+  if (!identityArgument) fail("folder-scoped core.sshCommand does not declare an -i identity file");
+  const identityFile = resolveConfigPath(
+    identityArgument[1] ?? identityArgument[2] ?? identityArgument[3],
+    repository,
+  );
+  if (!existsSync(identityFile))
+    fail(`folder-scoped SSH identity file does not exist: ${identityFile}`);
+
+  const remoteOutput = git(repository, ["ls-remote", "--symref", options.remote, "HEAD"], {
+    timeout: options.timeout,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: "0",
+      GCM_INTERACTIVE: "Never",
+    },
+  });
+  const remoteReference = /^ref:\s+(\S+)\s+HEAD$/m.exec(remoteOutput)?.[1] ?? null;
+  const remoteHead = /^([a-f0-9]{40,64})\s+HEAD$/m.exec(remoteOutput)?.[1] ?? null;
+  if (!remoteReference || !remoteHead) fail("remote HEAD could not be resolved deterministically");
+
+  const upstream = git(repository, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], {
+    allowFailure: true,
+  }).trim();
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        status: "ready",
+        repository,
+        branch,
+        required_branch: options.branch,
+        upstream: upstream || null,
+        remote: {
+          name: options.remote,
+          push_url: pushUrl,
+          head_reference: remoteReference,
+          head: remoteHead,
+        },
+        git_identity: {
+          name: name.value,
+          email: email.value,
+        },
+        ssh: {
+          folder_scoped: true,
+          config_source: sshCommand.origin,
+          identity_file: identityFile,
+          process_override: false,
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+} catch (error) {
+  process.stderr.write(
+    `deploy preflight failed: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+}
+
+function parseArguments(arguments_) {
+  const parsed = { repository: ".", remote: "origin", branch: null, timeout: 15_000 };
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === "--repository")
+      parsed.repository = requiredValue(arguments_, ++index, argument);
+    else if (argument === "--remote") parsed.remote = requiredValue(arguments_, ++index, argument);
+    else if (argument === "--branch") parsed.branch = requiredValue(arguments_, ++index, argument);
+    else if (argument === "--timeout-ms") {
+      parsed.timeout = Number(requiredValue(arguments_, ++index, argument));
+    } else if (argument === "--help") {
+      process.stdout.write(
+        "Usage: preflight.mjs [--repository PATH] [--remote NAME] [--branch NAME] [--timeout-ms 1000..60000]\n",
+      );
+      process.exit(0);
+    } else fail(`unknown argument: ${argument}`);
+  }
+  if (!Number.isInteger(parsed.timeout) || parsed.timeout < 1_000 || parsed.timeout > 60_000) {
+    fail("--timeout-ms must be an integer from 1000 to 60000");
+  }
+  if (parsed.branch !== null && !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(parsed.branch)) {
+    fail("--branch must be a plain Git branch name");
+  }
+  return parsed;
+}
+
+function requiredValue(arguments_, index, option) {
+  const value = arguments_[index];
+  if (!value || value.startsWith("--")) fail(`${option} requires a value`);
+  return value;
+}
+
+function git(repository, arguments_, settings = {}) {
+  const result = spawnSync("git", ["-C", repository, ...arguments_], {
+    encoding: "utf8",
+    timeout: settings.timeout ?? 10_000,
+    env: settings.env ?? process.env,
+    windowsHide: true,
+  });
+  if (result.error) fail(`${formatGit(arguments_)}: ${result.error.message}`);
+  if (result.status !== 0) {
+    if (settings.allowFailure) return "";
+    const detail = (result.stderr || result.stdout || `exit ${result.status}`).trim();
+    fail(`${formatGit(arguments_)}: ${detail}`);
+  }
+  return result.stdout;
+}
+
+function requiredConfig(repository, key) {
+  const output = git(repository, ["config", "--show-origin", "--get", key]);
+  const tab = output.indexOf("\t");
+  if (tab < 1) fail(`effective ${key} has no origin`);
+  const value = output.slice(tab + 1).trim();
+  if (!value) fail(`effective ${key} is empty`);
+  return { origin: output.slice(0, tab).trim(), value };
+}
+
+function isFolderScoped(repository, gitDirectory, sshSource) {
+  if (isWithin(sshSource, gitDirectory)) return true;
+  const output = git(
+    repository,
+    ["config", "--show-origin", "--get-regexp", "^includeIf\\..*\\.path$"],
+    {
+      allowFailure: true,
+    },
+  );
+  return output
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .some((line) => {
+      const tab = line.indexOf("\t");
+      const space = line.indexOf(" ", tab + 1);
+      if (tab < 1 || space < 0) return false;
+      const declaringConfig = configPath(line.slice(0, tab), repository);
+      const key = line.slice(tab + 1, space);
+      const includedConfig = resolveConfigPath(
+        line.slice(space + 1).trim(),
+        dirname(declaringConfig),
+      );
+      return (
+        samePath(includedConfig, sshSource) &&
+        includeConditionMatches(key, gitDirectory, declaringConfig)
+      );
+    });
+}
+
+function includeConditionMatches(key, gitDirectory, declaringConfig) {
+  const match = /^includeif\.(gitdir\/i|gitdir):(.+)\.path$/i.exec(key);
+  if (!match) return false;
+  let condition = match[2];
+  if (condition.startsWith("~/") || condition.startsWith("~\\")) {
+    condition = resolve(homedir(), condition.slice(2));
+  } else if (condition.startsWith("./") || condition.startsWith(".\\")) {
+    condition = resolve(dirname(declaringConfig), condition.slice(2));
+  }
+  const portableCondition = portable(condition);
+  const patternSource = portableCondition
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replaceAll("**", "ZAIP_DOUBLE_STAR_SENTINEL")
+    .replace(/\*/g, "[^/]*")
+    .replaceAll("ZAIP_DOUBLE_STAR_SENTINEL", ".*")
+    .replace(/\?/g, "[^/]");
+  const prefixPattern = portableCondition.endsWith("/") ? `${patternSource}.*` : patternSource;
+  return new RegExp(`^${prefixPattern}$`, match[1].toLowerCase() === "gitdir/i" ? "i" : "").test(
+    portable(gitDirectory),
+  );
+}
+
+function resolveConfigPath(value, base) {
+  const unquoted = unquote(value);
+  if (unquoted === "~") return homedir();
+  if (unquoted.startsWith("~/") || unquoted.startsWith("~\\")) {
+    return resolve(homedir(), unquoted.slice(2));
+  }
+  return resolve(isAbsolute(unquoted) ? unquoted : resolve(base, unquoted));
+}
+
+function configPath(origin, base) {
+  const value = origin.trim().replace(/^file:/, "");
+  return resolveConfigPath(value, base);
+}
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('"')) return trimmed;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed.slice(1, -1);
+  }
+}
+
+function isWithin(candidate, parent) {
+  const path = relative(resolve(parent), resolve(candidate));
+  return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+}
+
+function samePath(left, right) {
+  const normalize = (value) => portable(resolve(value)).toLowerCase();
+  return normalize(left) === normalize(right);
+}
+
+function portable(value) {
+  return value.replace(/\\/g, "/");
+}
+
+function isSshUrl(value) {
+  return /^ssh:\/\//i.test(value) || /^[^/@\s]+@[^:/\s]+:.+/.test(value);
+}
+
+function formatGit(arguments_) {
+  return `git ${arguments_.join(" ")}`;
+}
+
+function fail(message) {
+  throw new Error(message);
+}

package/templates/.zaip-aios/templates/skills/zaip-skill-github-setup/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: zaip-skill-github-setup
+description: Configure Git, GitHub, and folder-scoped SSH when requested; setup alone never authorizes a push.
+---
+
+# Set up GitHub
+
+Configure the requested Git/GitHub state idempotently while preserving unrelated repositories and identities. Separate setup, first commit, and publication so that creating or configuring a repository cannot push by accident.
+
+## Select the requested mode
+
+Support these independent modes:
+
+1. Initialize Git in an existing folder.
+2. Create a GitHub repository.
+3. Attach a local repository to an existing GitHub repository.
+4. Configure folder-scoped Git identity and SSH.
+5. Create the first local commit.
+6. Publish only when the user also explicitly requests deploy/push.
+
+Before creating remote state, require the repository owner/name and visibility. Before generating a key, require the intended identity, key path, and passphrase policy. These choices materially affect security and cannot be guessed.
+
+## Inspect before mutation
+
+Run applicable checks:
+
+```powershell
+git status --short --branch
+git rev-parse --show-toplevel
+git config --show-origin --get user.name
+git config --show-origin --get user.email
+git config --show-origin --get core.sshCommand
+git remote -v
+gh auth status
+```
+
+Also inspect existing conditional includes and SSH host aliases without printing private-key contents. Preserve all unrelated entries.
+
+## Initialize a local repository
+
+- Use `git init -b main` when no repository exists.
+- Review or create an appropriate `.gitignore` before staging.
+- Add `.gitattributes` when byte-stable cross-platform files or checksums require it.
+- Scan for secrets and files above GitHub limits.
+- Do not nest a repository accidentally inside another repository.
+
+## Configure identity and SSH by folder
+
+Prefer conditional Git configuration scoped to an absolute folder root rather than changing the active identity globally.
+
+1. Reuse an existing dedicated SSH key when the user selected it.
+2. Generate a new key only when explicitly requested; never overwrite an existing key or assume an empty passphrase.
+3. Register only the public key with GitHub, for example through `gh ssh-key add` after confirming the authenticated account.
+4. Create or update a dedicated identity config containing `user.name`, `user.email`, and—when this is the chosen pattern—`core.sshCommand` with `IdentitiesOnly=yes`.
+5. Add one idempotent `includeIf "gitdir/i:<absolute-root>/"` entry to the main Git config.
+6. Alternatively, reuse a pre-existing SSH host alias such as `github-<identity>` and set the remote to that alias. Do not mix patterns unnecessarily.
+7. Test the configured host/account without inline key overrides.
+
+Back up a configuration file before changing it, bound edits to the selected identity/root, and never display private key material.
+
+## Create or attach the GitHub repository
+
+- Confirm `gh auth status` matches the selected owner/account.
+- Check whether `<owner>/<repository>` already exists before creation.
+- Create with explicit visibility and without `--push`, using a non-interactive `gh repo create` form supported by the installed CLI.
+- Add `origin` only when absent.
+- If `origin` exists, validate it and stop on a mismatch unless the user explicitly asked to replace it.
+- Prefer SSH when the selected setup is SSH; retain HTTPS when the user selected HTTPS.
+
+## Create the first commit
+
+An explicit request for initialization or first commit authorizes `git add -A` and one local commit, including new files, after ignore/secret/size/diff gates pass. Use the agent prefix table from the repository's deploy policy, defaulting to `[AUTO][<AGENT>]`. Do not push merely because a commit was created.
+
+## Publish only when explicit
+
+When the same user request explicitly includes deploy/push, read and follow `../zaip-skill-github-deploy/SKILL.md` after setup succeeds. Otherwise finish with the exact push command the user may authorize later.
+
+## Verify and report
+
+Verify effective identity origins, current branch, remote URLs, SSH/GitHub account, last commit, and clean/expected worktree state. Report every created or modified local/global config path and remote resource. Never claim publication unless the remote branch was actually updated.

package/templates/.zaip-aios/templates/skills/zaip-skill-github-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP GitHub Setup"
+  short_description: "Configure GitHub repositories and SSH"
+  default_prompt: "Use $zaip-skill-github-setup to configure this repository for GitHub safely."

package/templates/.zaip-aios/templates/skills/zaip-skill-move-prd/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: zaip-skill-move-prd
+description: Explicitly move, cancel, execute, or deliver a ZAIP PRD while keeping child SPECs, Tasks, Changes, and Executions lifecycle-consistent. Use only when a user asks to move a PRD between dashboard columns, execute it, cancel or finalize it, or repair descendants left behind by a PRD status change.
+---
+
+# Mover PRD com descendentes
+
+Use apenas comandos canônicos ZAIP. Não edite status diretamente no frontmatter nem mova arquivos de lifecycle manualmente.
+
+## Exigir autoridade explícita
+
+1. Criação, revisão, aprovação de conteúdo, refinamento, planejamento e `prepare` não autorizam movimento.
+2. Sem pedido explícito de movimento ou execução, mantenha PRD `draft` em Definição e encerre o trabalho.
+3. Não trate “está pronto”, “aprovado” ou ausência de pendências como comando de promoção sem verbo de ação dirigido ao lifecycle.
+
+## Identificar o movimento
+
+1. Resolva o PRD por ID e inspecione seu estado com `node .zaip-aios/bin/zaip.mjs prd show <PRD-ID> --json`.
+2. Trate “finalizar”, “concluir” e “entregar” como `deliver`; trate “cancelar” e “abandonar” como `cancel`.
+3. Trate “mova/coloque em Pronto para Executar” como `prd ready`. Trate “execute/inicie a execução” como autorização para preparar, se necessário, e então usar `prd execute`; não simule transições com edição de arquivo.
+
+## Aplicar a política parental
+
+- `prd cancel <PRD-ID>` cancela o PRD e, pela lógica do framework, todas as SPECs, Tasks, Changes e Executions descendentes ainda abertas.
+- Descendentes já `delivered`, `completed`, `failed` ou `cancelled` permanecem imutáveis.
+- `prd deliver <PRD-ID>` entrega SPECs ativas somente após os gates provarem que Changes, Tasks, Executions, Runs, Acceptance Criteria e Evidences estão concluídos. Nunca converta descendentes incompletos em sucesso.
+- `prd prepare <PRD-ID> --plan <plano>` valida e persiste o plano, mas preserva `draft` e a coluna Definição.
+- `prd ready <PRD-ID>` exige PreparedPlan, move o PRD para `ready` e promove somente as SPECs selecionadas pelo plano.
+- `prd execute <PRD-ID>` materializa o PreparedPlan e ativa apenas as SPECs selecionadas; um pedido explícito de execução permite esse caminho a partir de `draft` preparado.
+- Um PRD `draft` precisa ser preparado antes de `ready` ou `execute`; não force `active` sem plano e SPECs válidas.
+
+## Verificar
+
+1. Leia novamente o PRD e liste SPECs com `spec list --prd <PRD-ID> --json`.
+2. Após `prepare`, confirme que PRD e SPECs continuam `draft`; após `ready`, confirme que apenas as selecionadas ficaram `ready`.
+3. Confirme no resultado do cancelamento os arrays `cascade.specs`, `cascade.tasks`, `cascade.changes` e `cascade.executions`.
+4. Se um descendente aberto permanecer fora da cascata, pare e reporte vínculo quebrado; não o associe por semelhança de título.

package/templates/.zaip-aios/templates/skills/zaip-skill-move-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Move PRD"
+  short_description: "Promova PRDs somente com pedido explícito."
+  default_prompt: "Use $zaip-skill-move-prd para mover este PRD somente conforme minha solicitação explícita de lifecycle."

package/templates/.zaip-aios/templates/skills/zaip-skill-move-spec/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: zaip-skill-move-spec
+description: Explicitly move, cancel, execute, or deliver a ZAIP SPEC while keeping descendant Tasks, Changes, and Executions lifecycle-consistent. Use only when a user asks to move a SPEC between dashboard columns, execute it, cancel or finalize it, or repair Tasks left behind by a SPEC status change.
+---
+
+# Mover SPEC com descendentes
+
+Use apenas comandos canônicos ZAIP. Não edite status diretamente no frontmatter nem mova arquivos de lifecycle manualmente.
+
+## Exigir autoridade explícita
+
+1. Criação, revisão, aprovação de conteúdo, refinamento, planejamento e `prepare` não autorizam movimento.
+2. Sem pedido explícito de movimento ou execução, mantenha SPEC `draft` em Planejamento e encerre o trabalho.
+3. Não trate “está pronta”, “aprovada” ou ausência de pendências como comando de promoção sem verbo de ação dirigido ao lifecycle.
+
+## Identificar o movimento
+
+1. Resolva a SPEC por ID e inspecione seu estado com `node .zaip-aios/bin/zaip.mjs spec show <SPEC-ID> --json`.
+2. Trate “finalizar”, “concluir” e “entregar” como `deliver`; trate “cancelar” e “abandonar” como `cancel`.
+3. Trate “mova/coloque em Pronto para Executar” como `spec ready`. Trate “execute/inicie a execução” como autorização para preparar, se necessário, e então usar `spec execute`.
+
+## Aplicar a política parental
+
+- `spec cancel <SPEC-ID>` cancela a SPEC e, pela lógica do framework, todas as Tasks, Changes e Executions descendentes ainda abertas.
+- Descendentes já `completed`, `failed` ou `cancelled` permanecem imutáveis.
+- `spec deliver <SPEC-ID>` só entrega após os gates provarem conclusão das Tasks, Changes, Executions, Runs, Acceptance Criteria e Evidences. Nunca marque Tasks incompletas como concluídas.
+- `spec prepare <SPEC-ID> --plan <plano>` valida e persiste o plano, mas preserva `draft` e a coluna Planejamento.
+- `spec ready <SPEC-ID>` exige PreparedPlan e move somente a SPEC para `ready`.
+- `spec execute <SPEC-ID>` materializa seu PreparedPlan; um pedido explícito de execução permite esse caminho a partir de `draft` preparado, e uma SPEC governada pelo plano global de um PRD não cria uma Execution duplicada.
+- Não altere o PRD pai ao mover apenas uma SPEC.
+
+## Verificar
+
+1. Leia novamente a SPEC após o comando.
+2. Após `prepare`, confirme que a SPEC continua `draft`; após `ready`, confirme que somente ela ficou `ready`.
+3. Confirme no resultado do cancelamento os arrays `cascade.tasks`, `cascade.changes` e `cascade.executions`.
+4. Verifique que SPECs irmãs e suas Tasks não mudaram.
+5. Se uma Task aberta permanecer fora da cascata, pare e reporte vínculo quebrado; não a associe por título.

package/templates/.zaip-aios/templates/skills/zaip-skill-move-spec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Move SPEC"
+  short_description: "Promova SPECs somente com pedido explícito."
+  default_prompt: "Use $zaip-skill-move-spec para mover esta SPEC somente conforme minha solicitação explícita de lifecycle."

package/templates/.zaip-aios/templates/skills/zaip-skill-navigate-work/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: zaip-skill-navigate-work
+description: Navigate and refine pending ZAIP work without starting execution.
+---
+
+# Navegar pelo trabalho
+
+1. Comece por listagem compacta de metadados; nunca carregue corpos ou JSONL de todas as entidades.
+2. Filtre por `--status`, `--from`, `--to`, `--prd`, `--spec` ou `--task`; use `--limit` e continue com `--after <ID>`. Use `--all` apenas quando realmente necessário.
+3. O `index` retorna um `schema` e linhas compactas; `work_relations` contém até dois vínculos de lifecycle para navegação inicial. Abra `summary` para relações completas, preparação, custo, Requirements e ACs; use `show` depois de selecionar um ID.
+4. Diferencie lifecycle persistido de coluna: PRD `draft` fica em Definição, SPEC `draft` em Planejamento, Task avulsa `draft|planned` em Pronto para Executar, e `executing|verifying|completed|blocked|failed|cancelled` seguem suas colunas homônimas.
+5. Resolva a cadeia de relações e a visão macro antes de abrir detalhes.
+6. Ao selecionar um ID, carregue somente artefato ativo, Requirements/AC, Rules, decisões, código e testes relacionados.
+7. Permita comparar/refinar PRDs, SPECs e Tasks pendentes sem executar. Listar, mostrar ou revisar nunca implica `execute`.
+
+Exemplo: `zaip spec list --prd <PRD-ID> --status draft,ready --limit 25 --json`.

package/templates/.zaip-aios/templates/skills/zaip-skill-navigate-work/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Navigate ZAIP Work"
+  short_description: "Find and refine pending work without executing it."
+  default_prompt: "Use $zaip-skill-navigate-work to filter and inspect pending ZAIP work without starting execution."

package/templates/.zaip-aios/templates/skills/zaip-skill-observability/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: zaip-skill-observability
+description: Inspect ZAIP Runs, tokens, costs, rework, coverage, and macro aggregates.
+---
+
+# Analisar uso e custo
+
+Escolha um modo: `record`, `analyze` ou `reconcile`.
+
+## Record
+
+1. Todo turno deve possuir Run, mas somente trabalho executável possui Task. Pergunta read-only ou classificação incerta usa `phase: conversation`, `entrypoint: conversation` e `task_id: null`; continuação/refinamento/rework reutiliza o alvo da mesma thread. Quando virar trabalho novo, feche essa Run e abra outra com o mesmo `CONV-*` e o novo escopo. Tentativa iniciada por `execute` usa `execution` e exige `EXEC-*`, mesmo sem diff.
+2. Preserve `new` ou `rework`, entrada (`task`, `spec`, `prd`) e somente IDs ancestrais conhecidos. Não invente PRD/SPEC para Task-first nem atribua Change/Execution antes da materialização.
+3. Registre segmentos com `zaip run usage <RUN-ID> --phase ... --activity ...`. O timestamp da fonte é automático; informe `--initial-pack-tokens`, `--tool-output-tokens`, `--files-opened` e `--snippets-opened` quando disponíveis. Ausência de token/preço permanece `null`.
+4. Finalize toda Run e Sub-Run com status técnico `--status completed|failed|cancelled`. A Run raiz de Task aguarda o Sub-Run finalizador e então aplica `--task-outcome completed|blocked|failed|cancelled`; o status técnico pode ser `completed` enquanto gates insuficientes deixam a Task `blocked`.
+5. Classifique pela hierarquia e propósito: Run raiz tem `parent_run_id: null` e `run_purpose: orchestration`; Sub-Run possui pai e usa `execution`, `review`, `audit` ou `finalization`. Cada chamada de agente fixa agente, modelo e effort até terminar. Calls e ferramentas são eventos internos; quando observáveis, suas quantidades, resultados, tokens e custos são agregados na Run/Sub-Run, sem `CallProjection` ou tela própria.
+
+## Analyze e reconcile
+
+1. Filtre primeiro com `zaip run list --prd|--spec|--task|--execution|--change ... --status ... --from ... --to ... --limit ...`; use `run show` apenas nas Runs selecionadas.
+2. Agregue sem dupla contagem com `zaip run aggregate` e o mesmo filtro de escopo. Task soma Runs atribuídas; SPEC e PRD somam descendentes identificados.
+3. Exponha conversa, planejamento, execução, total, `new/rework`, cobertura de tokens e cobertura de preço. Compare resultado, duração, tentativas, AC/evidência e assertividade junto do custo.
+4. Reconcilie a mesma semântica no dashboard/Kanban e Zaip Cost Monitor, incluindo abas e contagens separadas de Runs e Sub-Runs, finalizadores, identidade `zaip-agent-*`, modelo/effort planejados, configuração efetiva, Calls conhecidas, tokens por segmento e concentração top-10. Divergência é finding; não injete JSONL bruto nem crie índice de conteúdo persistente. As projeções lifecycle descartáveis em `.agents/projections/runtime` são autorizadas.
+5. Reconciliação de telemetria pode ser auditada separadamente; reconciliação global de lifecycle só roda pelo popup confirmado ou por comando humano explícito. Nunca adicione varredura por turno, intervalo ou abertura do dashboard.

package/templates/.zaip-aios/templates/skills/zaip-skill-observability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Observability"
+  short_description: "Analyze Runs, tokens, costs, rework, and coverage."
+  default_prompt: "Use $zaip-skill-observability to reconcile phase-aware usage and macro costs for Tasks, SPECs, and PRDs."

package/templates/.zaip-aios/templates/skills/zaip-skill-openai-docs/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: zaip-skill-openai-docs
+description: Answer questions about OpenAI APIs, models, SDKs, Agents SDK, Responses API, Realtime API, Apps SDK, Codex, MCP, authentication, limits, or migrations using current official OpenAI documentation. Use whenever a user asks how an OpenAI product works, requests implementation guidance, compares current OpenAI capabilities, or needs exact API fields and citations.
+---
+
+# Consultar documentacao oficial OpenAI
+
+1. Para OpenAI API e produtos, use primeiro as tools do MCP `openaiDeveloperDocs`; nao responda apenas por memoria.
+2. Pesquise com consulta curta, selecione o resultado oficial mais relevante e leia a pagina antes de responder.
+3. Para campos, parametros e schemas, consulte tambem a referencia/OpenAPI oficial quando a tool estiver disponivel.
+4. Para Codex, configuração, MCP, skills, plugins ou comportamento das superficies, prefira o manual oficial do Codex; use o Docs MCP para lacunas especificas.
+5. Cite links oficiais usados e diferencie fato documentado, inferencia e comportamento observado localmente.
+6. Se o MCP estiver indisponivel, informe a limitacao e use somente fallback em `developers.openai.com` ou `platform.openai.com`.
+7. Nunca invente modelo, parametro, limite, preço, disponibilidade ou comportamento.
+8. Pedidos de implementacao podem exigir `OPENAI_API_KEY`, mas consultas de documentacao nao exigem chave. Nunca peça que a chave seja colada no chat.
+
+Leia `references/routing.md` apenas quando houver duvida sobre a fonte correta.

package/templates/.zaip-aios/templates/skills/zaip-skill-openai-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP OpenAI Docs"
+  short_description: "Consulte documentação oficial OpenAI via MCP"
+  default_prompt: "Use $zaip-skill-openai-docs para responder esta pergunta com a documentação oficial da OpenAI."

package/templates/.zaip-aios/templates/skills/zaip-skill-openai-docs/references/routing.md

@@ -0,0 +1,11 @@
+# Roteamento de fontes
+
+| Pergunta | Fonte primaria |
+|---|---|
+| Responses, Realtime, Agents ou Apps SDK | OpenAI Developer Docs MCP |
+| Campo ou parametro exato | OpenAPI/referencia oficial via MCP |
+| Modelo atual ou migracao | Guia oficial de modelos e migracao |
+| Codex, config.toml, MCP, skills ou plugins | Manual oficial do Codex |
+| Falha do MCP | developers.openai.com; depois platform.openai.com |
+
+Nao use blogs, snippets ou memoria como fonte autoritativa quando a documentacao oficial estiver disponivel.