@zaip-ai/cli 2.0.0 → 2.6.0

package/templates/.agents/skills/zaip-skill-database-migrations/scripts/export-manual-sql.test.mjs

@@ -0,0 +1,178 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import test from "node:test";
+import { exportManualSql } from "./export-manual-sql.mjs";
+
+function fixture(t) {
+  const root = mkdtempSync(join(tmpdir(), "zaip-manual-sql-"));
+  t.after(() => {
+    assert.equal(dirname(root), resolve(tmpdir()));
+    assert.match(root, /zaip-manual-sql-[^\\/]+$/);
+    rmSync(root, { recursive: true, force: true });
+  });
+  assert.equal(spawnSync("git", ["init", "-q", root], { windowsHide: true }).status, 0);
+  spawnSync(
+    "git",
+    ["-C", root, "remote", "add", "origin", "git@github.com:example/source-service.git"],
+    { windowsHide: true },
+  );
+  mkdirSync(join(root, ".agents/config"), { recursive: true });
+  writeFileSync(
+    join(root, ".agents/config/project.yaml"),
+    "project: {timezone: America/Sao_Paulo}\n",
+  );
+  writeFileSync(join(root, "proposal.sql"), "create table sample(id bigint primary key);\n");
+  return {
+    repository: root,
+    betaDeclined: true,
+    name: "criar-tabela-funcionalidade-meta-diagnosis",
+    sqlFile: "proposal.sql",
+    now: new Date("2026-09-07T15:33:00Z"),
+  };
+}
+
+test("missing beta alone never creates a folder without explicit refusal", (t) => {
+  const options = fixture(t);
+  for (const betaDeclined of [undefined, false, "true"]) {
+    assert.throws(
+      () => exportManualSql({ ...options, betaDeclined }),
+      /Explicit human beta refusal/,
+    );
+    assert.equal(existsSync(join(options.repository, "db-migrations")), false);
+  }
+});
+
+test("export uses Git root, project timezone and pending human status with traceability", (t) => {
+  const options = fixture(t);
+  const child = join(options.repository, "nested");
+  mkdirSync(child);
+  const result = exportManualSql({ ...options, repository: child });
+  assert.equal(
+    result.file,
+    join(
+      options.repository,
+      "db-migrations/2026-09-07-12-33-criar-tabela-funcionalidade-meta-diagnosis.sql",
+    ),
+  );
+  assert.equal(result.status, "pending_human_execution");
+  assert.equal(result.source_repository, "example/source-service");
+  assert.equal(result.source_sha, null);
+  const sql = readFileSync(result.file, "utf8");
+  assert.match(sql, /No agent or pipeline may execute/);
+  assert.match(sql, /create table sample/);
+  assert.equal(result.sha256, createHash("sha256").update(sql).digest("hex"));
+});
+
+test("same minute collisions produce distinct files and preserve earlier SQL", (t) => {
+  const options = fixture(t);
+  const first = exportManualSql(options);
+  const original = readFileSync(first.file, "utf8");
+  writeFileSync(
+    join(options.repository, options.sqlFile),
+    "alter table sample add column title text;",
+  );
+  const second = exportManualSql(options);
+  assert.match(second.file, /-2\.sql$/);
+  assert.equal(readFileSync(first.file, "utf8"), original);
+  assert.equal(readdirSync(dirname(first.file)).length, 2);
+});
+
+test("invalid input and invalid timezone fail before optional folder creation", (t) => {
+  const options = fixture(t);
+  for (const change of [{ name: "../unsafe" }, { name: "..." }, { sqlFile: "missing.sql" }]) {
+    assert.throws(() => exportManualSql({ ...options, ...change }));
+    assert.equal(existsSync(join(options.repository, "db-migrations")), false);
+  }
+  writeFileSync(
+    join(options.repository, ".agents/config/project.yaml"),
+    "project: {timezone: invalid/timezone}\n",
+  );
+  assert.throws(() => exportManualSql(options), /time zone/i);
+  assert.equal(existsSync(join(options.repository, "db-migrations")), false);
+});
+
+test("absent timezone explicitly uses UTC and normalizes Portuguese names", (t) => {
+  const options = fixture(t);
+  writeFileSync(join(options.repository, ".agents/config/project.yaml"), "project: {}\n");
+  const result = exportManualSql({ ...options, name: "Edição da tabela" });
+  assert.equal(result.timezone, "UTC");
+  assert.match(result.file, /2026-09-07-15-33-edicao-da-tabela\.sql$/);
+});
+
+test("existing junction cannot redirect SQL writes", (t) => {
+  const options = fixture(t);
+  const outside = join(options.repository, "other-directory");
+  mkdirSync(outside);
+  symlinkSync(
+    outside,
+    join(options.repository, "db-migrations"),
+    process.platform === "win32" ? "junction" : "dir",
+  );
+  assert.throws(() => exportManualSql(options), /real directory/);
+  assert.deepEqual(readdirSync(outside), []);
+});
+
+test("portable installed helper needs no node_modules and no deploy target change", (t) => {
+  const options = fixture(t);
+  const skills = join(options.repository, ".agents/skills");
+  const localScript = join(skills, "zaip-skill-database-migrations/scripts/export-manual-sql.mjs");
+  const parser = join(skills, "zaip-skill-github-deploy/scripts/yaml-parser.mjs");
+  mkdirSync(dirname(localScript), { recursive: true });
+  mkdirSync(dirname(parser), { recursive: true });
+  copyFileSync(join(import.meta.dirname, "export-manual-sql.mjs"), localScript);
+  copyFileSync(
+    resolve(import.meta.dirname, "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs"),
+    parser,
+  );
+  const before = readFileSync(join(options.repository, ".agents/config/project.yaml"), "utf8");
+  const result = spawnSync(
+    process.execPath,
+    [
+      localScript,
+      "--repository",
+      options.repository,
+      "--beta-declined",
+      "--name",
+      options.name,
+      "--sql-file",
+      options.sqlFile,
+    ],
+    { encoding: "utf8", windowsHide: true, env: { ...process.env, NODE_PATH: "" } },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(result.stdout).status, "pending_human_execution");
+  assert.equal(
+    readFileSync(join(options.repository, ".agents/config/project.yaml"), "utf8"),
+    before,
+  );
+});
+
+test("manual SQL remains blocked from automatic application publication", (t) => {
+  const options = fixture(t);
+  exportManualSql(options);
+  const preflight = resolve(
+    import.meta.dirname,
+    "../../zaip-skill-github-deploy/scripts/preflight.mjs",
+  );
+  const result = spawnSync(
+    process.execPath,
+    [preflight, "--repository", options.repository, "--scope", "frontend", "--resolve-branch"],
+    { encoding: "utf8", windowsHide: true },
+  );
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /cannot include database migrations/);
+});

package/templates/.agents/skills/zaip-skill-dependency-upgrade/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-dependency-upgrade
+description: Plan and verify safe runtime, library, tooling, manifest, lockfile, and compatibility upgrades.
+---
+
+# Upgrade dependencies
+
+Use when changing a runtime, library, package manager, framework, or tool version.
+
+1. Inventory direct and transitive consumers, supported engine range, release notes, lockfile effects, and generated artifacts.
+2. Define compatibility and rollback before modifying manifests. Do not mix unrelated upgrades with a focused repair.
+3. Update source, configuration, docs, tests, and generated outputs affected by the actual version contract.
+4. Validate a clean install and the focused build or test paths; distinguish an installation failure from an application regression.
+5. Record unresolved upstream incompatibilities and the exact pre-upgrade recovery point.

package/templates/.agents/skills/zaip-skill-dependency-upgrade/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Dependency Upgrade"
+  short_description: "Plan and verify compatible dependency upgrades"
+  default_prompt: "Use $zaip-skill-dependency-upgrade to safely upgrade this dependency or runtime."

package/templates/.agents/skills/zaip-skill-deployment-pipeline/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: zaip-skill-deployment-pipeline
+description: Build and verify application delivery pipelines with identifiable artifacts, migrations, smoke checks, and rollback.
+---
+
+# Deliver application changes
+
+Use when configuring an application build-to-environment delivery process. It does not authorize a deployment.
+Read `references/runtime-shapes.md` when selecting API, worker, or static-site delivery.
+
+1. Define source revision, immutable artifact identity, environment configuration names, promotion rule, migration order, smoke check, and rollback trigger.
+2. Separate artifact build, migration, deploy, and verification so each result is observable and recoverable.
+3. Ensure the deployed runtime can expose the tested artifact revision without leaking build or credential details.
+4. Test pipeline failure handling and a recoverable rollout in a non-production target when available.
+5. For an explicit external deployment request, compose with `$zaip-skill-github-deploy` or the approved cloud workflow.

package/templates/.agents/skills/zaip-skill-deployment-pipeline/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Deployment Pipeline"
+  short_description: "Design verifiable application delivery pipelines"
+  default_prompt: "Use $zaip-skill-deployment-pipeline to design this application delivery pipeline."

package/templates/.agents/skills/zaip-skill-deployment-pipeline/references/runtime-shapes.md

@@ -0,0 +1,3 @@
+# Runtime shapes
+
+Build and deploy Hono API and BullMQ worker containers separately so scaling and failure are observable per role. Build React/Vite and Astro outputs as static assets for Cloudflare Pages; they are not worker containers. Migration promotion follows expand before compatible application rollout and contract only after the compatibility window. This skill defines a pipeline; use the guarded GitHub skill only for an explicit Git publication request.

package/templates/.agents/skills/zaip-skill-design-system/SKILL.md

@@ -5,7 +5,9 @@ description: Govern canonical design-system tokens, catalog specimens and anchor
 
 # Design System
 
-Use this skill when creating or editing the central design language. Manu owns
+Use this skill when creating or editing the central design language. First load and
+apply [`RULE-DESIGN-SYSTEM-CENTRAL`](../../rules/design-system-central-contract.md); it is the mandatory, exception-free
+contract for user-requested creation or customization. Manu owns
 `.agents/design/DESIGN.md`, `.agents/design/tokens.json`,
 `.agents/design/apps/catalog/**`, canonical component specimens, and the frontend of
 the framework pages `design-system` and `componentes`.
@@ -15,21 +17,26 @@ the framework pages `design-system` and `componentes`.
 Call Manu whenever a change creates or edits a central design rule, design token,
 canonical component contract, or either design catalog page. A feature component that
 merely lives in a directory named `components` is not central design work and remains
-with the delivery specialist unless it changes the shared contract.
+with the delivery specialist unless it changes the shared contract. Manu coordinates
+its renderable representation in `#/components` with that specialist; this does not
+move business logic or delivery ownership to the central catalog.
 
 ## Workflow
 
-1. Read the current `DESIGN.md`, tokens, catalog specimens, and consuming pages.
+1. Read `RULE-DESIGN-SYSTEM-CENTRAL`, the current `DESIGN.md`, tokens,
+   catalog specimens, and consuming pages.
 2. State the design problem, affected products, accessibility constraints, and
    compatibility impact.
 3. Update `DESIGN.md` as the human-readable source of principles, voice, layout,
    typography, color, motion, interaction, accessibility, and component rules.
 4. Update machine-readable tokens without duplicating contradictory values.
-5. Implement or update the canonical specimen and both catalog presentations when the
-   rule is user-visible.
-6. Check representative consumers for regressions; coordinate with Doug or Jonny when
+5. For every new UI component, ensure a renderable `#/components` representation with
+   applicable states or variants; keep local business logic in its delivery module.
+6. For every user-requested design-system creation or edit, update the canonical
+   specimen and both catalog presentations as required by the Rule.
+7. Check representative consumers for regressions; coordinate with Doug or Jonny when
    their product surfaces must adopt the new contract.
-7. Verify design artifacts and rendered catalog pages before recording evidence.
+8. Verify design artifacts and rendered catalog pages before recording evidence.
 
 ## Required outcomes
 
@@ -37,8 +44,12 @@ with the delivery specialist unless it changes the shared contract.
 - Tokens have stable semantic names and do not encode a single page's implementation.
 - Canonical components document anatomy, states, variants, content rules, keyboard
   behavior, focus, contrast, responsiveness, and do/don't guidance.
-- The `design-system` page exposes foundations and tokens.
-- The `componentes` page exposes reusable component specimens and states.
+- `#/design-system` exposes foundations and tokens.
+- `#/components` is the componentes page and exposes reusable component specimens and states.
+- Every new UI component has a renderable `#/components` example with applicable states or variants;
+  a Storybook entry or name alone is insufficient.
+- Component specimens retain the active `DESIGN.md` identity and pertinent tokens without turning
+  local components into global contracts.
 - Both pages consume the same central source instead of maintaining independent copies.
 - Breaking changes include migration guidance and affected consumers.
 

package/templates/.agents/skills/zaip-skill-dev-environment/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-dev-environment
+description: Inspect and prepare a reproducible local development environment without exposing local configuration values.
+---
+
+# Prepare development environment
+
+Use for a new checkout, onboarding, or a local runtime failure. This concerns the consumer application; framework installation remains `$zaip-skill-setup`.
+
+1. Read project configuration and manifests before proposing prerequisites. Never install packages, start services, or execute package scripts during discovery.
+2. Run `node .agents/skills/zaip-skill-dev-environment/scripts/inventory.mjs [root]` for a names-and-presence-only inventory. Read its grammar before extending it.
+3. Compare observed runtimes, package manager, declared services, ports, and environment-variable names with documented requirements.
+4. Report exact missing prerequisites and safe start commands; retain unavailable state rather than inventing a successful service.
+5. Verify an authorized setup through the smallest relevant health or build command and record the environment limits.

package/templates/.agents/skills/zaip-skill-dev-environment/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Development Environment"
+  short_description: "Inspect safe local prerequisites and setup"
+  default_prompt: "Use $zaip-skill-dev-environment to inventory this checkout and identify local setup prerequisites."

package/templates/.agents/skills/zaip-skill-dev-environment/references/inventory-contract.md

@@ -0,0 +1,7 @@
+# Inventory grammar and output
+
+Run `node .agents/skills/zaip-skill-dev-environment/scripts/inventory.mjs [root]`.
+
+`root` is an optional filesystem directory and defaults to the current directory. No other argument is accepted. The helper reads only `package.json`, lockfile names, project configuration presence, and dotenv file names. It never runs package scripts, installs dependencies, or writes files.
+
+It emits one UTF-8 JSON object with `schema_version: 1`, relative `root: "."`, Node version, file-presence booleans, package-manager name, sorted package-script names, and sorted dotenv variable names per present dotenv file. It never emits dotenv values or package-script values.

package/templates/.agents/skills/zaip-skill-dev-environment/scripts/inventory.mjs

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+
+const argumentsList = process.argv.slice(2);
+if (argumentsList.length > 1) throw new Error("Usage: inventory.mjs [root]");
+const [rootArgument = "."] = argumentsList;
+const root = resolve(rootArgument);
+const packagePath = resolve(root, "package.json");
+const dotenvNames = [".env", ".env.local", ".env.development", ".env.test", ".env.example"];
+const result = {
+  schema_version: 1,
+  root: ".",
+  node: process.version,
+  files: {},
+  package_manager: null,
+  package_scripts: [],
+  environment_names: {},
+};
+
+for (const name of [
+  "package.json",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "bun.lockb",
+  ".agents/config/project.yaml",
+]) {
+  result.files[name] = existsSync(resolve(root, name));
+}
+for (const name of dotenvNames) {
+  const path = resolve(root, name);
+  if (!existsSync(path)) continue;
+  result.environment_names[name] = namesFromDotenv(await readFile(path, "utf8"));
+}
+if (result.environment_names[".env.example"]) {
+  const present = new Set(
+    Object.entries(result.environment_names)
+      .filter(([name]) => name !== ".env.example")
+      .flatMap(([, names]) => names),
+  );
+  result.required_environment_names = result.environment_names[".env.example"];
+  result.missing_required_environment_names = result.required_environment_names.filter(
+    (name) => !present.has(name),
+  );
+}
+if (result.files["package.json"]) {
+  const manifest = JSON.parse(await readFile(packagePath, "utf8"));
+  result.package_manager =
+    typeof manifest.packageManager === "string"
+      ? manifest.packageManager.split("@")[0]
+      : lockManager(result.files);
+  result.package_scripts = Object.keys(manifest.scripts ?? {}).sort();
+} else result.package_manager = lockManager(result.files);
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+
+function namesFromDotenv(source) {
+  return [
+    ...new Set(
+      source.split(/\r?\n/).flatMap((line) => {
+        const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        return match?.[1] ? [match[1]] : [];
+      }),
+    ),
+  ].sort();
+}
+function lockManager(files) {
+  return files["pnpm-lock.yaml"]
+    ? "pnpm"
+    : files["package-lock.json"]
+      ? "npm"
+      : files["yarn.lock"]
+        ? "yarn"
+        : files["bun.lockb"]
+          ? "bun"
+          : null;
+}

package/templates/.agents/skills/zaip-skill-disaster-recovery/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: zaip-skill-disaster-recovery
+description: Plan and verify recoverable application data and service restoration with scoped backups, RPO, RTO, and evidence.
+---
+
+# Prepare recovery
+
+Use for backup, restore, continuity, or data-loss recovery planning.
+Read `references/recovery-scope.md` to separate service recovery evidence.
+
+1. Identify services, data classes, dependencies, owners, recovery point objective, recovery time objective, and acceptable loss.
+2. Define backup scope, retention, encryption, access, restore ordering, and verification criteria; do not call a backup useful without restore evidence.
+3. Test restoration in an isolated target with representative data and verify application behavior, permissions, and job safety afterward.
+4. Record gaps, manual actions, external dependencies, and evidence freshness.
+5. Do not perform destructive recovery drills or alter production backups without explicit authorization.

package/templates/.agents/skills/zaip-skill-disaster-recovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Disaster Recovery"
+  short_description: "Plan and verify recoverable service restoration"
+  default_prompt: "Use $zaip-skill-disaster-recovery to plan and test recovery for this application."

package/templates/.agents/skills/zaip-skill-disaster-recovery/references/recovery-scope.md

@@ -0,0 +1,3 @@
+# Recovery scope
+
+PostgreSQL restore, Supabase Storage restore, Redis recovery, and runtime configuration recovery are separate procedures with separate evidence. After restoration, prove the application starts, tenant permissions remain effective, and queued work does not duplicate a durable effect. Redis cache loss can be acceptable; queue loss may not be.

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

@@ -1,10 +1,12 @@
 ---
 name: zaip-skill-execution
-description: Execute prepared ZAIP work explicitly, materialize its DAG, and close Runs with evidence.
+description: Execute prepared ZAIP work only on explicit intent; materialize its DAG and close Runs with evidence.
 ---
 
 # Executar trabalho preparado
 
+Carregue [a governança de execução e delegação](references/runtime-governance.md) antes da entrega ou dispatch. Perguntas read-only sem descendentes usam somente o kernel de RULE-CORE e a skill de domínio pertinente.
+
 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. Antes de selecionar executor, carregue as Rules aplicáveis; para decisão comercial, use `$RULE-SPECIALIST-ROUTING` como fonte única da matriz de roteamento. Ao construir ou diagnosticar o plano externo, leia [o contrato compacto](references/prepared-plan.md).
@@ -13,10 +15,10 @@ Use esta skill somente quando o usuário pedir execução. `prepare` não autori
 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. Antes de implementar, consulte `zaip task assurance TASK --json`, aplique [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md) e [o fluxo de candidato e preparo](references/candidate-workflow.md). Falta de prova obrigatória impede aceite, não trabalho independente.
-7. Para toda Task com mutação, produza um commit canônico isolado antes de `completed`, com provider efetivo exclusivamente `CODEX` ou `CLAUDE` e sem `AUTO`. Linhagem evidenciada usa `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <título da Task>` com blocos disponíveis; Task sem PRD/SPEC usa `[CODEX|CLAUDE] [Task-first:XXXX] <título da Task>`. Limite o assunto a 96 caracteres sem cortar palavras, preserve IDs completos disponíveis nos trailers `ZAIP-PRD`, `ZAIP-SPEC`, `ZAIP-Task`, `ZAIP-Change`, `ZAIP-Execution` e `ZAIP-Agent`, e não combine Tasks no mesmo commit. Commit funcional sem Task só é permitido na exceção explícita de deploy particionado e usa `[CODEX] <título funcional>` sem `ZAIP-Task`.
+7. Para toda Task com mutação, produza um commit canônico isolado antes de `completed`, com provider efetivo exclusivamente `CODEX` ou `CLAUDE` e sem `AUTO`. Linhagem evidenciada usa `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <título da Task>` com blocos disponíveis; Task sem PRD/SPEC usa `[CODEX|CLAUDE] [Task-first:XXXX] <título da Task>`. Limite o assunto a 96 caracteres sem cortar palavras, preserve IDs completos disponíveis nos trailers `ZAIP-PRD`, `ZAIP-SPEC`, `ZAIP-Task`, `ZAIP-Change`, `ZAIP-Execution` e `ZAIP-Agent`, e não combine Tasks no mesmo commit. Commits de produto, inclusive deploy particionado, exigem essa identidade; somente alterações em `.agents/records/` e `.local/` dispensam Task. Valide o índice e siga [o contrato portátil](../zaip-skill-task/references/commit-policy.md).
 8. 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.
 9. Em cada `run usage`, leia `budget.context_refresh_required` e `budget.checkpoint_required`. O runtime grava o checkpoint sanitizado em `.local/checkpoints/`; quando sinalizado, reconstrua contexto somente de IDs ativos, diff e findings, descarte outputs brutos antigos e continue apenas com autoridade.
-10. Em falha operacional, use retry limitado; em falha lógica, crie repair/rework explícito. Nunca esconda uma tentativa.
+10. Falha operacional transitória recebe retry limitado; impedimento essencial deixa a Task `blocked`; falha lógica exige correção localizada ou repair/rework explícito. Antes de uma próxima correção, carregue o [ciclo de correção e bloqueio](references/correction-cycle.md). Nunca esconda uma tentativa.
 11. 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.
 12. Para delegação Codex, Sub-Run é somente subagente nativo de colaboração (`spawn_agent`). `create_thread` e `fork_thread` criam chats independentes e só podem ocorrer por pedido explícito do usuário; nunca os use como Sub-Run, fallback, retry ou prova de delegação. Se delegação nativa estiver indisponível, relate a limitação em vez de criar chat independente. Nome de catálogo, `task_name`, título ou prompt não provam ancestralidade nativa. Antes de repetir a mesma delegação limitada, aguarde ou reutilize seu filho pendente; capture somente ancestralidade/metadados observados em resultados nativos de spawn/terminal do host ou eventos SubagentStart/SubagentStop.
 13. Interaction read-only sem descendentes termina após a resposta, sem executor/finalizador. Para interaction com descendente delegado e para delivery, depois que todos os Sub-Runs de trabalho terminarem invoque `zaip-agent-finalizer` como último filho com propósito `finalization`. Não inicie novos filhos depois dele; auto-settlement nunca fecha interaction com descendente ativo. Isso também vale para `cancelled`: o orquestrador aplica a decisão Gui pela CLI; comandos diretos Task/SPEC/PRD nunca terminalizam. Ausência, interrupção ou falha do Gui deixa a Execution inconclusiva como `blocked`.

package/templates/.agents/skills/zaip-skill-execution/references/correction-cycle.md

@@ -0,0 +1,7 @@
+# Ciclo de correção e bloqueio
+
+Carregue esta referência somente antes de uma nova correção. Falha operacional transitória, cuja recuperação é esperada, recebe retry limitado; impedimento essencial deixa a Task `blocked`; falha lógica exige correção localizada ou repair/rework explícito.
+
+Registre nos findings, Change ou Run existentes somente resultados observáveis: falha, tentativa e resultado, aprendizado ou hipótese nova, e próxima ação e teste discriminante; não registre raciocínio privado. Se a mesma falha reaparecer após uma correção, revise a hipótese antes de editar novamente. Evidência pode refutá-la mesmo quando o teste não passa. Diff, ID cosmético ou mera ausência de erro não demonstram avanço.
+
+Preserve escopo e critérios de aceite; evite melhorias opcionais e valide primeiro a hipótese específica, repetindo validação ampla somente por mudança relevante ou gate exigido. Respeite os limites e contadores existentes, sem criar paralelos; um replanejamento não os reinicia nem cria identidades novas para ganhar tentativas. Sem rota fundada, ou quando o limite aplicável se esgota, marque `blocked` com a condição objetiva de retomada no lifecycle. Astra só é usado onde a política atual permite; Task avulsa preserva modelo e effort selecionados pelo host.

package/templates/.agents/skills/zaip-skill-execution/references/runtime-governance.md

@@ -0,0 +1,13 @@
+# Governança de execução e delegação
+
+Carregue antes de executar uma entrega ou delegar. Este contrato detalha o kernel de RULE-CORE; perguntas diretas read-only não precisam desta expansão.
+
+- `RULE-CORE` e `RULE-WORKFLOW`, já carregadas antes desta referência, são a fonte para configuração, autoridade externa, captura, PRD/SPEC/Task lifecycle, Git-only/deploy, perguntas, verbos, credenciais e plano visível. Aplique-as integralmente; esta referência só acrescenta a governança de execução e delegação abaixo.
+- Em modo manual carregue `RULE-MODEL-ORCHESTRATION` antes da primeira resposta visível; aviso não bloqueia nem altera seleção. Com Codex/delegação use apenas `codex_name` do catálogo, formato `zaip-agent-NOME`, recursivamente; proíba `default`, `worker`, `explorer` e tipos ad-hoc.
+- Para delegação Codex, Sub-Run ZAIP é somente subagente nativo de colaboração (`spawn_agent`). `create_thread` e `fork_thread` criam chats independentes e exigem pedido explícito do usuário; nunca são Sub-Run, fallback, retry ou prova de delegação. Se delegação nativa estiver indisponível, relate a limitação em vez de criar chat independente. Nome de catálogo, `task_name`, título ou prompt não prova ancestralidade nativa. Antes de repetir a mesma delegação limitada, aguarde ou reutilize seu filho pendente e capture somente ancestralidade/metadados observados em resultados nativos de spawn/terminal do host ou eventos SubagentStart/SubagentStop.
+- Cada `client_turn_id` observável tem uma Execution idempotente/claim atômico; sem ele use identidade local sem prometer idempotência. `interaction` read-only sem descendentes é conversa sem Task artificial e termina após a resposta entregue, sem executor ou finalizador; interaction com trabalho delegado e `delivery` exigem executor/finalizador. `delivery` é trabalho materializado e reuso exige kind/origem compatíveis. A raiz é `zaip-agent-orchestrator`; quando a barreira é exigida escolha executor por capacidade, permita reviewer/auditor/integrator e termine com `zaip-agent-finalizer` em `finalization`, após descendentes, bloqueando novas chamadas.
+- Hooks são best-effort: após cada spawn/terminal o orquestrador também executa `zaip subagent capture` idempotente com metadados reais. Use session/turn filhos, `agent-id=agent_path`, `parent-agent-id=client_thread_id` da raiz e turn distinto por chamada. Quando um evento terminal observado expõe somente agent_path, status, identidade catalogada e pai exato, `capture-terminal` aceita apenas `zaip-agent-finalizer` ou executor elegível para delivery com capacidade `task-delivery`; exige também `parent-run-id` igual ao `run_id` da raiz ativa exata, pois um client thread pode conter raízes concorrentes. O último segmento do agent_path deve ser seu `codex_task_name` canônico. O propósito deriva da identidade validada e session/turn/model/provider/usage permanecem indisponíveis; o fallback nunca substitui captura rica nem inventa modelo, effort, tokens ou custo.
+- Em `model_orchestration.mode:auto`, selecione automaticamente apenas origens em `automatic_sources` (`spec`,`prd`); fixe modelo/effort no início de cada Run/Sub-Run distinta, herde nas calls internas e exija nova chamada para mudar. Task avulsa preserva seleção manual, sem inferir `default_model`.
+- Somente ao avaliar escalada diagnóstica difícil para Astra, carregue `RULE-ASTRA-DIAGNOSTIC`: evidência obrigatória, `high`, quota persistente de três diagnósticos por Task e devolução para executor Luna/Terra/Sol. Não carregue essa expansão em consultas comuns.
+- Todo PreparedPlan PRD/SPEC traz `model_signals` por Task; o framework persiste `model_profile`, `task-risk-v1` e motivos, usando `runtime_defaults`, `runtime`, política/defaults sem `standard` silencioso. Não infira fase/complexidade/transversalidade/ambiguidade/rework/custo/capacidade por contagem de arquivos; use sinais, fase/agente e capacidades. Cabeçalho e `model.selection.recorded` repetem a seleção enviada.
+- Plano visível: `DEFINE:`, `PLAN:`, `EXECUTE:` ou `VERIFY:`, 3–4 passos (máximo 5); omita fase sem ação e combine trivialidades.

package/templates/.agents/skills/zaip-skill-external-integrations/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-external-integrations
+description: Implement bounded third-party API and webhook adapters with safe credentials, retries, verification, and replay handling.
+---
+
+# Integrate external systems
+
+Use for outbound providers, inbound webhooks, or vendor protocol changes.
+
+1. Establish the provider contract, data classification, auth method, timeout, rate limit, expected failures, and ownership boundary.
+2. Resolve credentials only for an already authorized action through `$zaip-skill-local-credentials`; never expose their values in evidence.
+3. Verify signatures before processing webhooks, use stable event identities for deduplication, and retain a bounded replay path.
+4. Place provider behavior behind an adapter and use sanitized fixtures for success, timeout, invalid response, and duplicate event cases.
+5. Do not enable production callbacks or mutate a provider account without explicit external authorization.

package/templates/.agents/skills/zaip-skill-external-integrations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "External Integrations"
+  short_description: "Build safe provider APIs and webhooks"
+  default_prompt: "Use $zaip-skill-external-integrations to implement this provider adapter or webhook."

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

@@ -5,7 +5,11 @@ description: Implement accessible frontend experiences in apps/frontend and dash
 
 # Entregar frontend
 
+Para componentes de UI novos ou alterados, carregue também
+`$zaip-skill-frontend-componentization`.
+
 1. Confirmar `apps/frontend/**` ou dashboard React (`.agents/dashboard/apps/frontend/**`, `.agents/dashboard/modules/**/src/react/**`); nunca autoriza runtime, SQLite ou server.
 2. Ler o contrato visual aplicável antes de alterar componentes e preservar acessibilidade, semântica e estados de carregamento/erro.
 3. Aplicar [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md): definir cenário/expectativa por AC, executar a interação afetada e conferir seu efeito; teste, typecheck e build são proporcionais e não substituem comportamento observado.
 4. Se houver impacto visual, obter e examinar screenshot real da versão carregada no estado pedido. No dashboard, preservar render determinístico e verificação do bundle servido. Indisponibilidade segue o fallback finito: mantém o AC visual pendente, não invalida prova técnica independente nem autoriza aprovação integral.
+5. Para publicação, usar somente a branch de validação configurada e o ambiente próprio de validação do frontend. A promoção para produção segue o [contrato de ambientes e acessos](../zaip-skill-backend/references/deployment-environments.md); consultas Supabase usam exclusivamente READ-ONLY-BETA ou READ-ONLY-PROD configurados.

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

@@ -0,0 +1,44 @@
+---
+name: zaip-skill-frontend-componentization
+description: Padronize UI e catálogo ao criar ou alterar componentes.
+---
+
+# Componentização frontend
+
+Use ao criar, alterar, renomear ou remover componentes de UI em `apps/frontend`,
+`apps/site`, dashboard React ou no catálogo de design. Não inicia migração dos
+componentes antigos: aplique somente ao componente tocado.
+
+1. Roteie a entrega: produto React/dashboard usa `$zaip-skill-frontend`; site
+   usa `$zaip-skill-website-readiness`; catálogo ou contrato central usa
+   `$zaip-skill-design-system` com Manu. Leia `RULE-DESIGN-SYSTEM-CENTRAL` e,
+   para dashboard, `RULE-DASHBOARD-UI-CONSISTENCY`.
+2. Antes de editar, inventarie consumidores, exportações públicas, catálogo,
+   stories e componentes próximos. Reutilize ou componha o que existe antes de
+   criar primitive, e registre o impacto de renomear/remover.
+3. Prefira variantes, `size`, slots e composição antes de duplicar. Classifique
+   o destino: a página só orquestra; componente local fica no domínio; UI
+   compartilhada só recebe contrato estável e consumidores reais. Não transforme
+   componente local em regra global nem crie primitives duplicadas.
+4. Extraia para hooks apenas lógica compartilhada ou efeitos; acesso a dados fica
+   em services. Estado visual local pode permanecer no componente. Mudança apenas
+   em hook ou service não cria entrada visual própria, mas atualiza o exemplo se
+   o comportamento observável do componente mudou.
+5. Para componente UI novo, alterado, renomeado ou removido, atualize a página
+   `Componentes` real em `.agents/design/apps/catalog/src/pages/ComponentsPage.tsx`
+   no mesmo Change. A página e a story devem consumir um espécime reutilizável e
+   os mesmos fixtures estáveis, renderizando o componente real pela fronteira
+   pública quando isso não acoplar produtos.
+6. Quando Storybook existir, mantenha a story alinhada ao espécime; ela nunca
+   substitui `#/components`. Fixtures não usam API, autenticação ou tempo atual.
+   Em Astro ou entre produtos sem dependência válida, use um fallback nativo ou
+   adaptador renderizável sem forçar island React; revalide o adaptador a cada
+   mudança. Cubra variantes e estados aplicáveis: padrão, foco/teclado,
+   desabilitado, carregamento, vazio e erro, além de largura estreita relevante.
+7. Em dashboard, inventarie e reutilize `@zaip-ai/dashboard-ui`; tabelas usam
+   `DataTable`, salvo Decision explícita. Não crie tabela ou primitive paralela.
+8. Ao renomear ou remover, retire exports, imports, stories, catálogo e referências
+   obsoletas. Valide consumidores, acessibilidade e os exemplos renderizados.
+
+O catálogo documenta a implementação existente; ele não exige migração global
+nem importa automaticamente componentes de produtos distintos.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Componentization"
+  short_description: "Standardize UI components and catalog"
+  default_prompt: "Use $zaip-skill-frontend-componentization to create or change UI components with coherent catalog examples."

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

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-frontend-data-flows
+description: Build reliable React data flows for remote state, forms, errors, pagination, and concurrent user actions.
+---
+
+# Build frontend data flows
+
+Use when React UI reads or mutates remote application state.
+
+1. Map the user-visible loading, empty, success, validation, authorization, and failure states before wiring data.
+2. Keep API services and request contracts outside presentation components; carry cancellation and request identity through concurrent transitions.
+3. Prevent stale responses from replacing newer state and disable or serialize destructive duplicate actions where the contract requires it.
+4. Preserve accessible feedback, focus behavior, and meaningful error recovery.
+5. Test relevant state transitions against the actual API contract or a controlled contract fixture.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Data Flows"
+  short_description: "Build reliable React remote state flows"
+  default_prompt: "Use $zaip-skill-frontend-data-flows to implement this React data flow."

package/templates/.agents/skills/zaip-skill-general-operations/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: zaip-skill-general-operations
-description: Deliver bounded operational artifacts when no mandatory specialist scope applies. Use for documents, presentations, spreadsheets, process artifacts, and comparative research; do not use for regulated governance work or external acts.
+description: Answer operational questions and deliver bounded documents, presentations, spreadsheets or processes; exclude specialist governance and external acts.
 ---
 
-# Executar operações gerais
+# Operações proporcionais
 
-1. Delimite o resultado, público, fontes, formato, write scope e critério de aceitação; trate fatos ausentes como pendências, nunca como dados inferidos.
-2. Se houver capability ou escopo obrigatório de produto, design, marketing, dados, segurança, cloud, frontend, backend, website ou governança, devolva ao orquestrador para a rota especialista.
-3. Produza o artefato delimitado e uma verificação proporcional. Para identidade visual existente, siga o contrato da Manu; para conteúdo de marketing, devolva a rota para Lúcia.
-4. Pesquisa comparativa usa apenas fontes autorizadas e registra critérios, evidência e incertezas. Não contrate, envie dados, assine, publique ou execute ato externo.
-5. Quando faltar autoridade humana, entregue a minuta, checklist, lacunas e a ação humana exata; a entrega não fica sem resultado por falta dessa autoridade.
+- Responda consultas, explicações e resumos no formato pedido, usando fontes e incertezas explícitas, sem arquivo ou questionário obrigatório.
+- Para entrega persistente, carregue [o fluxo de entrega](references/extended-workflow.md): resultado, público, fontes, formato, escopo e verificação proporcional.
+- Domínios obrigatórios seguem o especialista; referência citada não muda o dono da entrega. Não invente dados ou aprovação.
+- Ato externo exige autoridade vigente; prepare a minuta e indique pendências quando faltar autorização. Interaction read-only não cria Task/Change; entrega segue lifecycle e ACs. Engenharia só se aplica ao trabalho técnico.
+
+Para documento, resumo salvo ou organização de contexto simples, delimitada e de baixo impacto, use o [perfil editorial `lite`](../zaip-skill-task/SKILL.md#assurance-proporcional) e selecione `--risk lite`. Não o use para código, configuração, instruções de agentes, dado sensível, migração, decisão crítica ou ato externo.