@zaip-ai/cli 0.1.0 → 1.0.1

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

@@ -0,0 +1,36 @@
+---
+name: zaip-skill-execution
+description: Execute prepared ZAIP work explicitly, materialize its DAG, and close Runs with evidence.
+---
+
+# Executar trabalho preparado
+
+Use esta skill somente quando o usuário pedir execução. `prepare` não autoriza mutação nem promoção para `ready`; quando a execução foi pedida explicitamente, prepare o PRD/SPEC ainda em `draft`, se necessário, e então execute sem exigir outra confirmação intermediária.
+
+1. Carregue o PreparedPlan e valide hash, origem, Requirements/AC, DAG, write scopes e estado atual. Ao construir ou diagnosticar o plano externo, leia [o contrato compacto](references/prepared-plan.md).
+2. Materialize idempotentemente Change, Tasks e Execution antes da primeira alteração do produto.
+3. A partir da tentativa explícita de `execute`, classifique uso como `execution`; inicie Execution, Changes, Tasks elegíveis e Runs com atribuição ao nível de entrada (`task`, `spec` ou `prd`). Ausência de diff não retroage a fase: registre `changed_files` vazio e o resultado real.
+4. Execute a ordem topológica. Paralelize apenas Tasks independentes cujos arquivos, módulos, migrations, ambientes e recursos não conflitem.
+5. Antes de integrar agentes paralelos, compare diffs, testes e efeitos; reconcilie o resultado no workspace canônico.
+6. Registre decisões humanas/IA, uso por fase, evidências por AC, testes, evals e arquivos alterados.
+7. Respeite a política do plano: use `zaip verify --changed --risk <risk>` no modo `scoped`; reserve `pnpm verify` para `full`, risco critical ou gate final exigido.
+8. Em cada `run usage`, leia `budget.context_refresh_required` e `budget.checkpoint_required`. O runtime grava o checkpoint sanitizado em `.agents/projections/runtime/checkpoints/`; quando sinalizado, reconstrua contexto somente de IDs ativos, diff e findings, descarte outputs brutos antigos e continue apenas com autoridade.
+9. Em falha operacional, use retry limitado; em falha lógica, crie repair/rework explícito. Nunca esconda uma tentativa.
+10. Cada tentativa usa uma Run raiz do `zaip-agent-orchestrator`; subagentes e fases materialmente distintas usam Sub-Runs relacionadas por `parent_run_id`. Cada Run/Sub-Run fixa agente, modelo e effort; retry técnico preserva a configuração e qualquer mudança deliberada abre outra chamada de agente.
+11. Depois que todos os Sub-Runs de trabalho terminarem, invoque `zaip-agent-execution-finalizer` como último filho de qualquer Execution com propósito `finalization`. Não inicie novos filhos depois dele. A CLI aplica seu resultado restrito; ausência, interrupção ou falha deixa a Execution inconclusiva como `blocked`.
+12. SPEC/PRD permanece `active` entre Runs filhas e só entra em verificação após todas as Tasks; a Run filha não entrega nem bloqueia automaticamente o pai.
+
+## Paralelismo
+
+- A unidade de isolamento é a Task; a Execution mantém a DAG global, inclusive entre SPECs de um PRD.
+- O agente pode escolher execução sequencial mesmo com paralelismo permitido.
+- Toda integração final é uma dependência explícita e precisa repetir os gates relevantes no resultado combinado.
+
+## Runtime autônomo opt-in
+
+1. Leia `execution.runtime`. Ausente ou `manual` preserva a execução materializada tradicional; somente `autonomous` autoriza invocar o provider configurado.
+2. Injete `model_orchestration` somente quando `mode` for `auto` e a origem da Execution estiver em `automatic_sources`. O contrato canônico permite apenas `spec` e `prd`; uma Execution de `task` preserva a seleção manual do host.
+3. Em autonomia, exija raiz Git limpa, worktree registrada por Task, commit final sem alterações pendentes, diff dentro dos write scopes e merge abortável em conflito.
+4. Use o menor limite de paralelismo entre projeto, plano, provider e squad. Tasks `lite` têm uma tentativa; `standard` e `critical` no máximo três tentativas de desenvolvimento/reparo.
+5. Checkpoints opacos ficam somente em `.zaip-aios/local-data`; não copie token de retomada para records rastreados. Critical recebe contexto fresco e verificador independente.
+6. A validação tipada acontece dentro da worktree no commit candidato antes da integração. Falha de assurance não pode ser convertida em sucesso pelo coordenador.

package/templates/.agents/skills/zaip-skill-execution/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "ZAIP Execution"
+  short_description: "Orchestrate explicit ZAIP execution and Task DAGs."
+  default_prompt: "Use $zaip-skill-execution to execute prepared Task, SPEC, or PRD work and orchestrate its DAG safely."
+policy:
+  allow_implicit_invocation: false

package/templates/.agents/skills/zaip-skill-execution/references/prepared-plan.md

@@ -0,0 +1,31 @@
+# PreparedPlan V2 compacto
+
+Use este contrato quando o prepare exigir uma DAG externa. Para uma Task manual sem dependências, prefira `zaip task prepare <TASK-ID>`; com `depends_on`, forneça o plano completo em `--plan`.
+
+## Fluxo canônico
+
+1. Crie um JSON de draft sem `schema_version`, `hash` nem `dag.topological_order`.
+2. Rode `zaip plan build --draft <draft.json> --output <plan.json>` para calcular ordem e hash canônicos.
+3. Rode `zaip plan validate --plan <plan.json>`.
+4. Persista no pai com `zaip prd prepare <ID> --plan <plan.json>`, `zaip spec prepare <ID> --plan <plan.json>` ou `zaip task prepare <ID> --plan <plan.json>`.
+5. Remova o JSON intermediário quando ele não for evidência necessária; o PreparedPlan persistido no artefato pai é canônico.
+
+## Campos do draft
+
+- `revision`: inteiro positivo.
+- `source`: `{type: "task", task_id}`, `{type: "spec", spec_id}` ou `{type: "prd", prd_id}`.
+- `execution_id`: ID `EXEC-*` pré-alocado.
+- `prepared_at`: timestamp ISO 8601 com offset.
+- `policy`: `failure_policy` (`stop_on_terminal_failure` ou `continue_independent`), `max_parallelism` positivo, `max_operational_retries` e `max_repair_cycles_per_task` não negativos.
+- `blueprints.changes[]`: `key`, `id`, `title`, `short_name`, `risk`, `source`, Requirements/AC e `requirement_impact`.
+- `blueprints.tasks[]`: `key`, `id`, `change_id`, `title`, `short_name`, `objective`, `risk`, `priority`, `owner`, Requirements/AC e `write_scopes`.
+- `dag.nodes[]`: um nó por Task com `task_id` e `depends_on`.
+
+## Invariantes
+
+- Use IDs reais de Requirements/AC e IDs pré-alocados únicos; nunca invente referências durante o prepare.
+- Cada Task aponta para uma Change do mesmo plano e aparece exatamente uma vez na DAG.
+- Em plano de PRD, toda Change usa `source: {type: "prd", prd_id, spec_id}` com uma SPEC filha real; `spec_id` não pode ser nulo.
+- Em plano de SPEC ou Task, a origem da Change deve coincidir com a origem do plano.
+- Use paths workspace-relative em `write_scopes`. Tasks independentes não podem disputar scopes; modele dependência quando o compartilhamento for intencional.
+- Não calcule hash ou ordem manualmente e não edite o PreparedPlan depois de persistido. Gere nova revisão antes da execução; após materialização, trate correção como rework.

package/templates/.agents/skills/zaip-skill-frontend-launcher/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: zaip-skill-frontend-launcher
+description: Create and validate hidden Windows launchers for reliable local frontend sessions.
+---
+
+# Criar executável de frontend
+
+1. Identifique o frontend, seu build estático, a rota inicial e se o launcher pertence ao produto
+   ou a uma ferramenta local em `.agents`. Preserve `apps -> modules -> packages`.
+2. Leia [o contrato do launcher](references/launcher-contract.md) e inspecione launchers existentes
+   antes de criar outro padrão.
+3. Mantenha o executável no root da superfície e o código em `packages/local-runtime` e
+   `packages/windows-launcher`; não crie backend somente para servir arquivos estáticos.
+4. Sirva somente em loopback. Use porta preferencial configurável, busca limitada e health endpoint
+   com identidade do workspace.
+5. Persista sessão sanitizada no diretório temporário, isolada por hash do workspace. Sob lock
+   atômico, reutilize primeiro a sessão saudável e depois procure um runtime órfão reconhecível;
+   abra nova porta apenas quando nenhum deles existir.
+6. Use `.agents/config/src/icon_zaip.png` como fonte canônica padrão em workspaces ZAIP, salvo
+   identidade explicitamente definida pelo projeto. Valide formato e proporção, gere o `.ico`
+   temporário e compile com `/win32icon`; não mantenha cópias derivadas sem necessidade.
+7. Compile o wrapper C# como `winexe`. Inicie Node com `UseShellExecute=false`,
+   `CreateNoWindow=true` e `WindowStyle=Hidden`; resolva workspace e `node.exe` sem paths pessoais.
+8. Registre falhas apenas em log temporário e nunca inclua segredos, tokens ou dados do usuário.
+9. Teste ícone incorporado, path traversal, health, colisão de porta, lock obsoleto e dois cliques
+   consecutivos. O teste
+   real deve provar mesma porta, mesmo PID e um único runtime.
+10. Quando for fonte do framework, sincronize lock, template público, runtime e release; execute
+   validações de skill, arquitetura, build, pack e instalação limpa.

package/templates/.agents/skills/zaip-skill-frontend-launcher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Launcher"
+  short_description: "Cria launchers Windows para frontends locais"
+  default_prompt: "Use $zaip-skill-frontend-launcher para criar um executável Windows seguro para este frontend local."

package/templates/.agents/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/.agents/skills/zaip-skill-github-deploy/SKILL.md

@@ -1,84 +1,75 @@
 ---
 name: zaip-skill-github-deploy
-description: Commit and push a local Git repository safely to GitHub. Use only when the user explicitly asks in the current conversation to deploy, push, publish, publicar, subir, or send changes to GitHub; never trigger from an implied desire to prepare or review a repository.
+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 to GitHub
+# Deploy and repair GitHub publication
 
-Treat deploy as Git-only publication: stage the complete intended repository state, create a correctly attributed commit when needed, and push it to GitHub. Provider workflows may deploy applications afterward, but do not invoke Supabase, Vercel, cloud, package-registry, or database deployment commands without a separate explicit request.
+Treat deploy as Git-only publication. Provider deployment is separate and requires explicit authorization.
 
-## Authorization boundary
+## Authorization
 
-- Require an explicit deploy/push/publication request in the current conversation.
-- That request authorizes `git add -A`, including new files, a commit, and a normal push without another confirmation.
-- It does not authorize force push, history rewriting, remote replacement, credential changes, or deployment to another service.
-- If no changes exist, push already-committed local work when the explicit request still applies.
+- 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.
 
-## Preflight
+## Repair-loop integrity
 
-Run in the target repository:
+- 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.
 
-```powershell
-git status --short --branch
-git config --show-origin --get user.name
-git config --show-origin --get user.email
-git config --show-origin --get core.sshCommand
-git remote -v
-git branch --show-current
-```
+## Prove folder-scoped SSH first
 
-Preserve the identity resolved by the current folder. Enforce repository-specific identity expectations from `AGENTS.md`, `.agents`, or scoped Git configuration when present.
+From the repository root, select the explicit remote or `origin`, then run once:
 
-- Do not change account, key, remote, `core.sshCommand`, global Git config, or SSH config during deploy.
-- Never use `GIT_SSH_COMMAND` or an inline `ssh -i` override.
-- Accept an existing SSH host alias or scoped `core.sshCommand` when it resolves the intended account.
-- If the push URL is HTTPS, state that Git Credential Manager/token authentication will be used. Do not convert it silently.
-- Stop if the remote owner/repository conflicts with the user's explicit destination.
-
-Read remote state without publishing. If the target branch already exists, fetch normally and stop on a behind/diverged or non-fast-forward state; never repair it with force.
+```powershell
+node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin --branch demo
+```
 
-## Safety gates
+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.
 
-Before committing:
+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.
 
-1. Review `git status`, staged file names, and the diff summary.
-2. Run the repository's secret/security checks and inspect suspicious environment, key, certificate, state, or credential files without printing secret values.
-3. Block files at or above GitHub's 100 MB hard limit; use Git LFS only when the repository policy explicitly adopts it.
-4. Run `git diff --cached --check` and the repository's required ZAIP/test gates.
-5. Ensure ignored files are not accidentally force-added.
+## Review and validate
 
-Do not commit when a gate fails.
+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.
 
-## Commit identity
+## Synchronize and publish each cycle
 
-Prefix the commit message for the executing agent:
+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.
 
-| Agent | Prefix |
-| --- | --- |
-| Codex | `[AUTO][CODEX]` |
-| Claude | `[AUTO][CLAUDE]` |
-| Gemini | `[AUTO][GEMINI]` |
-| Roo | `[AUTO][ROO][15 AGENTS]` |
+Use the executing-agent commit prefix:
 
-Append workspace tags only when the repository defines them and only for workspaces actually changed. Keep the remaining message short and imperative.
+- Codex: `[AUTO][CODEX]`
+- Claude: `[AUTO][CLAUDE]`
+- Gemini: `[AUTO][GEMINI]`
+- Roo: `[AUTO][ROO][15 AGENTS]`
 
-## Publish
+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.
 
-1. Run `git add -A`.
-2. Commit when the index is non-empty using the required prefix.
-3. Push the current branch without SSH overrides:
-   - use `git push` when an upstream exists;
-   - use `git push -u <remote> <branch>` for the first publication.
-4. Never use `--force`, `--force-with-lease`, destructive cleanup, or history rewriting.
+- 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 report
+## Verify and monitor GitHub checks
 
-Run:
+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.
 
-```powershell
-git status --short --branch
-git log -1 --oneline
-git remote -v
-```
+## Success condition
 
-Confirm the remote branch contains the local commit when practical. Report repository path, branch, remote, effective identity, commit hash/title, and whether the worktree is clean. On failure, report the exact blocker without weakening authentication or safety controls.
+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/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "ZAIP GitHub Deploy"
-  short_description: "Commit and push safely to GitHub"
-  default_prompt: "Use $zaip-skill-github-deploy to publish the current repository to GitHub safely."
+  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: false
+  allow_implicit_invocation: true

package/templates/.agents/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/.agents/skills/zaip-skill-github-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zaip-skill-github-setup
-description: Set up Git and GitHub for a local project, including repository initialization, GitHub repository creation, attaching an existing remote, folder-scoped Git identity/SSH configuration, and a first local commit. Use when the user explicitly asks to create or configure a GitHub repository or SSH identity; setup alone never authorizes a push.
+description: Configure Git, GitHub, and folder-scoped SSH when requested; setup alone never authorizes a push.
 ---
 
 # Set up GitHub

package/templates/.agents/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/.agents/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."