@zaip-ai/cli 2.2.0 → 3.0.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,16 @@
+---
+name: zaip-skill-dev-environment
+description: Inspect and prepare a reproducible local development environment without exposing local configuration values.
+---
+
+# Prepare development environment
+
+Follow RULE-CORE host protection: never restart or shut down the user's computer. Inspect prerequisite installers and suppress automatic reboot using documented options; stop the step if suppression is uncertain. A pending OS restart is for the user to perform manually. Restarting an identified project process must never restart the OS.
+
+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
 
+Aplique a proteção do computador local de `RULE-CORE` antes de executar comandos e inclua-a no contexto de cada subagente. Nunca reinicie/desligue o PC, direta ou indiretamente, inclusive em validação, recuperação ou finalização. Reinício do SO fica exclusivamente a cargo do usuário.
+
 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.
@@ -15,28 +17,49 @@ 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`.
 14. 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.
-15. Resolva execução no menor grão explicitado: Task executa um nó elegível, SPEC executa sua DAG interna e PRD executa todas as SPECs selecionadas. Nunca amplie Task para SPEC/PRD por inferência.
+15. Resolva execução no menor grão que cubra o pedido inteiro: somente uma Task executa um nó elegível; toda a SPEC executa sua DAG interna; todo o PRD executa as SPECs selecionadas. Mencionar a primeira Task junto de “e as demais até terminar” não restringe um pedido macro a esse primeiro nó. Não amplie um pedido exclusivamente de Task para SPEC/PRD.
 16. “Conclua a execução” ou “finalize a implementação” em macro ativo continua Tasks e gates até resultado verdadeiro; não força `deliver`. “Desenvolva/melhore/aprimore” interrompe execução implícita, registra diagnóstico e cria plano/rework antes de nova promoção.
 
+## Captura correta antes de executar
+
+- Antes de capturar uma retomada ambígua, use `conversation resolve --intent continue --prd ID --json` (ou `--spec ID` / `--task ID`). A consulta não cria Run, não promove trabalho nem aprova gates; confira o alvo, a Execution e `start_args`. Sem alvo explícito, o foco vem da última raiz da mesma thread, nunca do último executor/revisor/Gui. Para um PRD conhecido use seu ID explícito, mesmo se a última raiz foi uma correção avulsa.
+- Resolva o alcance completo antes de iniciar a primeira parte. Em “Task X e o restante do PRD”, se X pertence à DAG, capture o PRD e delegue suas Tasks; mantenha Gui por Task e Gui parental ao final. Se X é uma entrega avulsa fora da DAG, não finja que pertence ao PRD: este runtime não possui coordenador multi-Execution. Identifique essa limitação antes de executar, preserve entregas já concluídas e não prometa uma sequência que exija trocar a raiz capturada. Uma correção avulsa já concluída não precisa ser reaberta para retomar o PRD.
+
+- Pedido para executar um PRD/SPEC existente é continuação da entrega, não nova autoria. Resolva o ID canônico e use `conversation start --intent continue --prd ID` (ou `--spec ID` / `--task ID` no menor grão pedido); inspecione a Run retornada e reutilize sua identidade. Não use `--definition` para executar um macro já criado.
+- `conversation start --intent new-work` já materializa e inicia Task, Change, Execution e Run. Não abra outra Run raiz para o mesmo turno. Uma repetição compatível deve reutilizar a identidade; intenção, alvo, modelo ou atribuição diferentes não são uma repetição compatível.
+- Antes de iniciar Tasks ou delegar, confira `execution_kind: delivery`, atribuição ao alvo e Execution correta. Uma Run `interaction` de definição não autoriza a implementação. Não reescreva seu header, altere IDs do cliente ou retire a proteção de correlação para convertê-la.
+- Quando a CLI rejeitar uma captura incompatível, preserve o estado e os IDs existentes e explique a divergência. Não avance manualmente as entidades para `executing` nem crie outro PRD/DAG como tentativa de recuperação. A proteção de um proprietário por invocação permanece obrigatória.
+
 ## Paralelismo
 
+### Execução nativa de uma DAG no Codex
+
+- `execution native-next EXEC --run RUN --contexts MAP.json --json` lê o PreparedPlan canônico e retorna envelopes; não inicia provider, não comprova autenticação nem constitui evidência de execução. O mapa associa IDs de Tasks a arquivos de contexto existentes construídos para o agente selecionado.
+- Inicie ou retome apenas Changes/Tasks elegíveis pelos comandos lifecycle. O macro despacha um `zaip-agent-orchestrator` por tentativa de Task, capturado com `subagent capture --event start ... --parent-run-id MACRO-RUN --task TASK`. A CLI deriva os ancestrais da DAG; a invocação delegada preserva `run_role: subagent`, propósito `orchestration` e pai nativo real. Não crie raízes fictícias nem atribua a mesma invocação a duas Tasks.
+- O orquestrador da Task despacha seus executores e revisores; eles retornam resultados e não criam filhos. Terminar um executor encerra somente sua Sub-Run. Após commit, integração aplicável, validações e `task verify`, Gui é o último filho direto do orquestrador da Task, irmão dos executores. Persista `run finalization TASK-RUN` com a decisão observada e IDs `EVD-*`. Encerrar o orquestrador sem Gui válido bloqueia somente sua Task; nunca aprova dependências bloqueadas.
+- Depois de cada Task, continue a DAG. Apenas após todas as Tasks e os gates de integração, use `execution verify`; o Gui do macro continua sendo o último filho do macro e decide seu fechamento. Um Gui de Task não entrega automaticamente a SPEC/PRD.
+- Uma invocação já atribuída a outra entrega não pode trocar de raiz no mesmo turno. Preserve sua identidade; não crie um novo trabalho independente ao retomar o PRD existente. O preflight deve detectar essa divergência antes da captura, não apenas após terminar a primeira parte. Não edite o PreparedPlan materializado nem reatribua Tasks históricas para contornar um conflito.
+- A hierarquia PRD/SPEC coordena a DAG, não exige níveis adicionais de agentes: o host despacha diretamente o orquestrador de cada Task, sem inserir um agente macro intermediário. Respeite profundidade, capacidade e orçamento reais; sequencie Tasks quando necessário. Sem delegação nativa no orquestrador, registre a limitação; não transfira a obrigação ao executor nem simule ancestralidade.
+- Perfis somente leitura retornam decisões/eventos; não gravam lifecycle. Aplique o relay do host autorizado descrito em `references/runtime-governance.md`, preservando Gui como último filho do orquestrador responsável. Não exija argumentos ausentes do schema nativo nem converta UUID em path. O host grava a decisão real antes do Stop canônico do Gui; ausência de captura ou persistência mantém resultado bloqueado e recuperável.
+- Aumento de escopo explicitamente autorizado em rework usa `task amend-scopes TASK --run RUN --expected-revision N --add-scopes PATH[,PATH] --reason MOTIVO`. O comando registra delta aditivo recuperável na Change, preservando snapshot, IDs, ACs, risco e contadores. Não use o motivo como substituto de autorização nem altere o PreparedPlan materializado.
+
 - 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
+## Runtime gerenciado e compatibilidade
 
-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.
+1. Leia `execution.runtime`. Novo padrão `managed` despacha PRD/SPEC pelo provider, mantendo avulsas diretas. Ausente/manual preserva execução tradicional; `autonomous` também permite Task gerenciada explícita. Legados já tentados exigem `task migrate-autonomy` revisado; nenhum consumo é zerado.
+2. Com `autonomy.version: 1`, aplique `RULE-AUTONOMY-DECISION` e seu ledger estável por Task. A seleção manual fica no principal avulso; subagentes seguem política automática com aviso. Sem esse bloco, preserve `automatic_sources` legado (`spec`,`prd`). Não alegue enforcement de orçamento/modelo em ferramenta nativa que não passou pelo dispatch gerenciado.
 3. Em autonomia, exija raiz Git limpa, worktree registrada por Task, commit final canônico sem alterações pendentes, diff dentro dos write scopes e merge abortável em conflito. A integração cria outro commit canônico por Task no histórico first-parent e referencia o SHA do candidato em `ZAIP-Product-Commit`.
-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.
+4. Use o menor paralelismo entre projeto, plano, provider e squad. Em `autonomy-v1`, orçamento por Task vem exclusivamente do preset congelado: Essencial 4/1, Equilibrado 10/3, Persistente ilimitado (execuções/replans); tempo não encerra Task. Risco/domain definem assurance, não esse orçamento. Só no contrato legado use as quotas anteriores por risco.
 5. Checkpoints opacos ficam somente em `.local`; 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/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

@@ -2,16 +2,26 @@
 
 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.
 
-- Leia `.agents/config/project.yaml`, esta Rule e Rules aplicáveis. Preserve domínio independente de framework, infraestrutura e fornecedor; respeite escopo/autoridade e peça direção antes de ação destrutiva, irreversível ou externa.
-- Pensar/explorar PRD/SPEC é `conversation`; criar persiste o pacote `draft` e PreparedPlan com telemetria, e `ready|execute` materializa a DAG. PRD/SPEC são opcionais; a entrada pode ser Task, SPEC ou PRD. PRD cancelado é imutável: crie sucessor `rework`.
-- Classifique/capture o turno: pergunta, análise pontual ou baixa confiança cria só Run `conversation`; continuação/refinamento/rework reutiliza foco; edição persistente, resultado independente ou pedido explícito cria Task de título semântico (nunca copiado/truncado do prompt). Pedido explícito no turno de `deploy|push|publicar|publicação GitHub` seleciona `$zaip-skill-github-deploy`, é Git-only e não materializa lifecycle; autoriza reconciliação limitada e commits funcionais apenas do diff pretendido/evidenciado, com pathspecs explícitos e sem inventar IDs ausentes. A seleção não autoriza outro provider, `git add -A`, force, segredos ou worktrees alheios.
-- Criar/refinar PRD/SPEC `draft` persiste macro/PreparedPlan em Execution `interaction`, sem Task, Change ou delivery, vinculada à Run/`creation_run_id`; agregue telemetria apenas observada/reconciliada. Fora disso, antes de mutação persistente no repositório/PC materialize Task, Execution, Change e Run raiz; pedido avulso entra em Execução. Só Git/deploy sem produto, manifests/telemetria gerados, `.git`, cache, build, teste e temporário são isentos; código, documentação e configuração nunca são.
-- Limite: cinco perguntas/turno, três turnos; registre decisões delegáveis. Autoridade, lei e segurança não delegáveis bloqueiam. Antes de bloquear ação já autorizada por credencial, aplique `$zaip-skill-local-credentials`: busque dotenv somente no projeto, trate-o como dados, selecione uma chave pertinente e injete-a apenas no subprocesso mínimo sem expor valores. Credencial ausente, ambígua ou comprovadamente inutilizável bloqueia; razão sanitizada. Resolva verbos por alvo/status em `RULE-WORKFLOW`: `execute` usa o menor grão, `implemente` sem alvo conversa, `desenvolva|melhore|aprimore` planeja/rework. Nunca invente tokens, custo, decisão, Evidence, teste ou resultado.
+- `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.
+- Hooks são best-effort: após cada spawn/terminal, o host autorizado a serviço do orquestrador executa `zaip subagent capture` idempotente com metadados reais. Na captura rica, preserve session/turn observados, `agent-id` com a identidade nativa retornada e `parent-agent-id`/`parent-run-id` do pai imediato exato; cada invocação preserva seu turn. 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 `autonomy-v1`, carregue `RULE-AUTONOMY-DECISION`. Task avulsa preserva seleção manual do principal, evita subagentes e só delega por necessidade concreta; quando delegar, informe que modelo/esforço dos filhos seguem a política ZAIP, sem obrigação de herdar o principal. Fixe configuração por chamada e registre seleção efetivamente observada. Sem `autonomy`, preserve o contrato legado de `automatic_sources` (`spec`,`prd`).
+- Escaladas seguem o perfil congelado: Essencial nunca Astra automático; Equilibrado Sol/high, Astra/high, Astra/high, com execução Astra/high elegível no terceiro bloco; Persistente sem quota total. `RULE-ASTRA-DIAGNOSTIC` descreve também compatibilidade legada. Não use título/volume como prova nem alegue mudança de modelo apenas pelo prompt.
 - 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.
+
+## Limites do host e relay de persistência
+
+- Gui pode ser o último filho para avaliar uma entrega que não conseguiu iniciar executor. Isso não concede sucesso: `executor_missing` mantém `completed` bloqueado mesmo com Evidence aprovada; decisões reais `blocked`/`failed` seguem o relay normal e preservam o motivo. Não crie executor cerimonial para satisfazer o fechamento. A exceção direta continua restrita à raiz Task autorizada desde a captura.
+
+- `execution.runtime: managed` despacha PRD/SPEC pelo provider e mantém avulsas diretas. Para a raiz Task direta, registre a referência humana em `--direct-authorization` desde a captura. Identidade e intenção sozinhas não concedem autorização. Esse contrato substitui somente o executor filho; nunca Evidence, revisão aplicável, Gui ou identidade observada. Não autorize retroativamente uma raiz fechada, macro ou filho.
+
+- Há exatamente um orquestrador responsável por tentativa de Task. Quando a raiz física já é Task-scoped, ela despacha executor/revisor e Gui diretamente: não inicia um Dave adicional. Somente uma raiz macro delega orquestradores de Tasks distintas; seus trabalhadores e Gui pertencem ao respectivo orquestrador. Coordenação e aceite parental não representam uma segunda tentativa da mesma Task.
+- Os nomes de ferramentas no catálogo são capacidades, não nomes literais de ferramentas do host. O orquestrador pode descobrir ferramentas diferidas no registro nativo e usar spawn/send/wait/close dos descendentes autorizados, inclusive com filesystem read-only. Essa permissão não autoriza persistência pelo perfil, chats independentes ou ampliação de sandbox. Declarar indisponibilidade exige conferir o registro efetivamente exposto.
+
+- `agent_type` usa o `codex_name` exato. Envie `task_name` somente se o schema da ferramenta nativa o oferecer; nesse caso use o `codex_task_name` exato. Sem esse parâmetro, use o perfil catalogado e preserve o UUID/nickname retornado, inclusive sufixos atribuídos pelo host. Nunca transforme UUID ou nickname em `agent_path` nem use nome como prova de ancestralidade.
+- Orquestrador e Gui com perfil `read-only` não executam comandos que escrevem records, locks ou recibos. Eles retornam eventos e decisão ao host autorizado. O host é o escritor do lifecycle, não um executor/finalizador substituto: não altera a decisão, identidade, pai ou evidências do agente.
+- A ordem canônica é início real, decisão observada de Gui, Stop e fechamento com a mesma decisão. Não imponha ao Gui espera ativa por recibos: ele pode devolver seu resultado terminal; o host usa `subagent capture --event stop` com a decisão real nos campos `task-outcome`, `summary`, `evidence`, `changed-files`, persistindo-a antes do Stop canônico. O relay rico aceita filho já terminal com responsável aberto, sem trocar metadados por fallback. Responsável fechado sem decisão exige nova tentativa autorizada. Não confunda horário observado com gravação, nem status nativo com decisão.
+- O fallback `capture-terminal` continua restrito ao contrato de path, pai e identidade já descrito. UUID com `agent_path: null` não satisfaz esse fallback. Falta de prova rica, conflito de ancestry ou falha do escritor bloqueia a entrega, sem recriar Tasks, inventar metadados, ampliar sandbox ou pedir a um executor que delegue Gui.

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.