@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/skills/zaip-skill-refactor-existing-code/scripts/validate-refactor-map.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const actions = new Set(["reuse", "move", "split", "adapt", "rewrite", "exclude"]);
+const visualModes = new Set(["preserve", "conform", "hybrid"]);
+const rollbackActions = new Set(["move", "split", "adapt", "rewrite"]);
+const inventoryKinds = new Set(["file", "symlink", "ignored-directory"]);
+const defaultIgnoredNames = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "target",
+  "vendor",
+]);
+const windowsReservedName = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const errors = [];
+const add = (message) => errors.push(message);
+const normalized = (value) => {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    path.isAbsolute(value) ||
+    path.win32.isAbsolute(value) ||
+    value.startsWith("\\\\")
+  ) {
+    return null;
+  }
+  const portable = value.replaceAll("\\", "/").replace(/^\.\//, "");
+  const parts = portable.split("/");
+  if (
+    portable.length === 0 ||
+    portable === "." ||
+    portable.startsWith("/") ||
+    portable.endsWith("/") ||
+    parts.some(
+      (part) =>
+        part.length === 0 ||
+        part === "." ||
+        part === ".." ||
+        part.includes(":") ||
+        part.endsWith(".") ||
+        part.endsWith(" ") ||
+        windowsReservedName.test(part),
+    )
+  ) {
+    return null;
+  }
+  return portable;
+};
+const normalizedRoot = (value) => (value === "." ? "." : normalized(value));
+
+const input = process.argv[2];
+if (!input || process.argv.length !== 3) {
+  console.error("Usage: node validate-refactor-map.mjs <refactor-map.json>");
+  process.exit(2);
+}
+
+let map;
+try {
+  map = JSON.parse(await readFile(input, "utf8"));
+} catch (error) {
+  console.error(`map read failed: ${error.message}`);
+  process.exit(1);
+}
+
+if (map?.schema_version !== 1) add("schema_version must be 1");
+if (!normalizedRoot(map?.source_root)) add("source_root must be a safe relative path or .");
+if (!normalizedRoot(map?.target_root)) add("target_root must be a safe relative path or .");
+const inventory = Array.isArray(map?.inventory?.units) ? map.inventory.units : null;
+const decisions = Array.isArray(map?.units) ? map.units : null;
+if (!inventory) add("inventory.units must be an array");
+if (!decisions) add("units must be an array");
+if (!Array.isArray(map?.inventory?.ignored)) add("inventory.ignored must be an array");
+const policyIgnoredNames = map?.inventory?.policy?.default_ignored_names;
+const policyIncludedNames = map?.inventory?.policy?.included_names;
+if (
+  !Array.isArray(policyIgnoredNames) ||
+  new Set(policyIgnoredNames).size !== defaultIgnoredNames.size ||
+  [...defaultIgnoredNames].some((name) => !policyIgnoredNames.includes(name))
+) {
+  add("inventory.policy.default_ignored_names must match the canonical policy");
+}
+if (
+  !Array.isArray(policyIncludedNames) ||
+  new Set(policyIncludedNames).size !== policyIncludedNames?.length ||
+  policyIncludedNames?.some((name) => !defaultIgnoredNames.has(name))
+) {
+  add("inventory.policy.included_names must be unique canonical ignored names");
+}
+const includedNames = new Set(Array.isArray(policyIncludedNames) ? policyIncludedNames : []);
+
+const inventoryPaths = new Set();
+const inventoryKeys = new Map();
+const ignoredInventoryPaths = new Set();
+const symlinkInventoryPaths = new Set();
+for (const unit of inventory ?? []) {
+  const source = normalized(unit?.path);
+  if (!source) add("each inventory unit requires a relative path");
+  else {
+    const key = source.toLocaleLowerCase("en-US");
+    if (inventoryKeys.has(key))
+      add(`case-insensitive inventory collision: ${inventoryKeys.get(key)} and ${source}`);
+    else {
+      inventoryKeys.set(key, source);
+      inventoryPaths.add(source);
+    }
+  }
+  if (!inventoryKinds.has(unit?.kind)) {
+    add(`inventory unit ${source ?? "(invalid path)"} has an invalid kind`);
+  }
+  if (unit?.kind === "file" && !/^[a-f0-9]{64}$/.test(unit?.sha256 ?? "")) {
+    add(`inventory file ${source ?? "(invalid path)"} requires sha256`);
+  }
+  if (unit?.kind === "ignored-directory" && source) ignoredInventoryPaths.add(source);
+  if (unit?.kind === "symlink" && source) symlinkInventoryPaths.add(source);
+  if (source) {
+    const baseName = source.split("/").at(-1);
+    if (
+      defaultIgnoredNames.has(baseName) &&
+      !includedNames.has(baseName) &&
+      unit?.kind !== "ignored-directory"
+    ) {
+      add(`default-ignored path must remain an ignored-directory unit: ${source}`);
+    }
+  }
+}
+const ignoredListKeys = new Set();
+for (const ignoredPath of map?.inventory?.ignored ?? []) {
+  const source = normalized(ignoredPath);
+  if (!source) add("inventory.ignored contains an invalid path");
+  else if (ignoredListKeys.has(source.toLocaleLowerCase("en-US"))) {
+    add(`inventory.ignored contains a duplicate path: ${source}`);
+  } else if (!ignoredInventoryPaths.has(source)) {
+    add(`ignored path lacks an ignored-directory inventory unit: ${source}`);
+  }
+  if (source) ignoredListKeys.add(source.toLocaleLowerCase("en-US"));
+}
+for (const source of ignoredInventoryPaths) {
+  if (!ignoredListKeys.has(source.toLocaleLowerCase("en-US"))) {
+    add(`ignored-directory unit is absent from inventory.ignored: ${source}`);
+  }
+}
+
+const seenSources = new Set();
+const decisionBySource = new Map();
+const destinations = [];
+for (const [index, unit] of (decisions ?? []).entries()) {
+  const label = `units[${index}]`;
+  const source = normalized(unit?.source);
+  if (!source) add(`${label}.source must be a relative path`);
+  else if (seenSources.has(source)) add(`duplicate decision for source: ${source}`);
+  else {
+    seenSources.add(source);
+    decisionBySource.set(source, unit);
+  }
+  if (!actions.has(unit?.action)) add(`${label}.action must be one of ${[...actions].join(", ")}`);
+  if (unit?.visual_mode !== undefined && !visualModes.has(unit.visual_mode))
+    add(`${label}.visual_mode is invalid`);
+  if (typeof unit?.rationale !== "string" || !unit.rationale.trim())
+    add(`${label}.rationale is required`);
+  if (typeof unit?.owner_task !== "string" || !/^TASK-[A-Z0-9-]+$/.test(unit.owner_task)) {
+    add(`${label}.owner_task must be a TASK-* identifier`);
+  }
+  if (typeof unit?.slice !== "string" || !unit.slice.trim()) add(`${label}.slice is required`);
+  if (typeof unit?.ui !== "boolean") add(`${label}.ui must be boolean`);
+  if (unit?.ui === true && !visualModes.has(unit?.visual_mode)) {
+    add(`${label}.visual_mode is required for UI units`);
+  }
+  if (unit?.ui === false && unit?.visual_mode !== undefined) {
+    add(`${label}.visual_mode is forbidden for non-UI units`);
+  }
+  if (!Array.isArray(unit?.gates) || unit.gates.length === 0)
+    add(`${label}.gates must be a non-empty array`);
+  else if (
+    unit.gates.some((gate) => typeof gate !== "string" || !gate.trim()) ||
+    new Set(unit.gates).size !== unit.gates.length
+  ) {
+    add(`${label}.gates must contain unique non-empty strings`);
+  }
+  if (!Array.isArray(unit?.depends_on)) add(`${label}.depends_on must be an array`);
+  else {
+    const dependencies = unit.depends_on.map(normalized);
+    if (dependencies.some((dependency) => !dependency))
+      add(`${label}.depends_on has an invalid path`);
+    if (new Set(dependencies).size !== dependencies.length)
+      add(`${label}.depends_on has duplicates`);
+    if (source && dependencies.includes(source)) add(`${label}.depends_on cannot reference itself`);
+  }
+  if (
+    rollbackActions.has(unit?.action) &&
+    (typeof unit?.rollback !== "string" || !unit.rollback.trim())
+  ) {
+    add(`${label}.rollback is required for ${unit.action}`);
+  }
+  if (unit?.destination !== undefined && unit?.destinations !== undefined) {
+    add(`${label} cannot use destination and destinations together`);
+  }
+  const rawDestinations =
+    unit?.destinations ?? (unit?.destination === undefined ? [] : [unit.destination]);
+  if (!Array.isArray(rawDestinations))
+    add(`${label}.destinations must be an array or destination a string`);
+  const validDestinations = (Array.isArray(rawDestinations) ? rawDestinations : []).map(normalized);
+  if (validDestinations.some((destination) => !destination))
+    add(`${label} has an invalid destination`);
+  const uniqueDestinations = [...new Set(validDestinations.filter(Boolean))];
+  if (uniqueDestinations.length !== validDestinations.length)
+    add(`${label} has duplicate destinations`);
+  if (unit?.action === "exclude") {
+    if (uniqueDestinations.length) add(`${label} exclude must not have destinations`);
+  } else if (unit?.action === "split") {
+    if (uniqueDestinations.length < 2) add(`${label} split requires at least two destinations`);
+  } else if (uniqueDestinations.length !== 1) add(`${label} requires exactly one destination`);
+  for (const destination of uniqueDestinations)
+    destinations.push({ destination, source: source ?? label });
+}
+
+for (const source of inventoryPaths)
+  if (!seenSources.has(source)) add(`missing decision for inventory path: ${source}`);
+for (const source of seenSources)
+  if (!inventoryPaths.has(source)) add(`decision source is absent from inventory: ${source}`);
+for (const source of ignoredInventoryPaths) {
+  if (decisionBySource.get(source)?.action !== "exclude") {
+    add(`ignored directory requires an exclude decision: ${source}`);
+  }
+}
+for (const source of symlinkInventoryPaths) {
+  if (decisionBySource.get(source)?.action !== "exclude") {
+    add(`symbolic link requires an exclude decision: ${source}`);
+  }
+}
+for (const [source, unit] of decisionBySource) {
+  for (const dependency of unit.depends_on ?? []) {
+    const normalizedDependency = normalized(dependency);
+    if (normalizedDependency && !inventoryPaths.has(normalizedDependency)) {
+      add(`unknown dependency for ${source}: ${normalizedDependency}`);
+    }
+  }
+}
+detectDependencyCycles(decisionBySource);
+
+destinations.sort((left, right) =>
+  left.destination.localeCompare(right.destination, "en", { sensitivity: "base" }),
+);
+for (let index = 1; index < destinations.length; index += 1) {
+  const previous = destinations[index - 1];
+  const current = destinations[index];
+  const previousKey = previous.destination.toLocaleLowerCase("en-US");
+  const currentKey = current.destination.toLocaleLowerCase("en-US");
+  if (currentKey === previousKey)
+    add(`destination collision: ${current.destination} (${previous.source}, ${current.source})`);
+  if (currentKey.startsWith(`${previousKey}/`))
+    add(`destination path collision: ${previous.destination} and ${current.destination}`);
+}
+
+if (errors.length) {
+  console.error(JSON.stringify({ valid: false, errors }, null, 2));
+  process.exit(1);
+}
+process.stdout.write(
+  `${JSON.stringify(
+    { valid: true, inventory_units: inventoryPaths.size, decisions: seenSources.size },
+    null,
+    2,
+  )}\n`,
+);
+
+function detectDependencyCycles(decisionsBySource) {
+  const visited = new Set();
+  const active = new Set();
+  const visit = (source, trail) => {
+    if (active.has(source)) {
+      add(`dependency cycle: ${[...trail, source].join(" -> ")}`);
+      return;
+    }
+    if (visited.has(source)) return;
+    active.add(source);
+    const unit = decisionsBySource.get(source);
+    for (const dependency of unit?.depends_on ?? []) {
+      const normalizedDependency = normalized(dependency);
+      if (normalizedDependency && decisionsBySource.has(normalizedDependency)) {
+        visit(normalizedDependency, [...trail, source]);
+      }
+    }
+    active.delete(source);
+    visited.add(source);
+  };
+  for (const source of decisionsBySource.keys()) visit(source, []);
+}

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

@@ -12,5 +12,5 @@ description: Create, version, validate, and promote ZAIP Requirements and Accept
 5. Para promover a `active`, exija todos os ACs cobertos por evidência, testes/evals terminais, referências válidas e ausência de regressão conhecida.
 6. Registre versão/proveniência; depreque com substituto explícito quando aplicável, sem apagar histórico ainda referenciado.
 7. Valide órfãos, duplicatas, AC sem evidência, aliases e referências quebradas antes de concluir.
-8. Diferencie assurance de Task e de entrega: `lite` usa exatamente 1 validação/1 Evidence, `standard` 2 ou 3, `critical` 3+ com controles independentes; SPEC/PRD adicionam pelo menos 3 validações/3 Evidences parentais, matriz completa e integração real.
+8. Diferencie assurance de Task e de entrega: `lite` usa ao menos 1 validação/1 Evidence e só exige teste para lógica/regressão declarada; `standard` usa 2 ou 3 validações, teste executado e Evidence consolidada; `critical` 3+ com quality review independente. Ative mutação, rollback, commit final e Evidence por AC somente pelos sinais observáveis declarados; extras nunca falham por quota. SPEC/PRD adicionam pelo menos 3 validações/3 Evidences parentais, matriz completa e integração real.
 9. Não promova Requirement com evidência de candidato antigo, sem commit/hash quando exigido ou com alegação de ambiente superior ao realmente validado.

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

@@ -14,5 +14,5 @@ Esta skill é read-only. Um pedido de revisão não autoriza corrigir, concluir
 5. Entregue findings priorizados com arquivo/linha quando possível, impacto, evidência e ação recomendada.
 6. Se não houver findings, declare riscos residuais e lacunas de evidência.
 7. Correções aprovadas exigem autorização separada e começam uma nova Task. Inicie seu Run com `--work-type rework`, relacione somente IDs já conhecidos e deixe ancestral desconhecido como `null`; nunca leia todo o histórico para adivinhar vínculos. A revisão original permanece imutável.
-8. Valide o perfil quantitativo e semântico: `lite` exatamente 1/1, `standard` exatamente 2/2 ou 3/3, `critical` 3+ e SPEC/PRD com 3+ artefatos parentais, matriz, integração, review independente e commit final.
+8. Valide o perfil quantitativo e semântico por mínimos, sem quotas máximas: `lite` exige pelo menos uma validação e uma Evidence, normalmente uma de cada, mas aceita extras legítimos; `standard` exige pelo menos duas validações no perfil base ou três no elevado e ao menos uma Evidence consolidada; `critical` exige três ou mais validações, quality review independente e somente os controles acionados pelos sinais persistidos; SPEC/PRD exigem três ou mais validações e Evidences parentais, matriz, integração e review independente.
 9. Para cleanroom, ambiente representativo ou produção, confira hash do candidato, identidade do ambiente, reviewer independente e Run observado; teste local não promove esses estados.

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

@@ -6,14 +6,14 @@ description: Create and validate project ZAIP Rules while preserving core Rules.
 # Manter Rules do projeto
 
 1. Confirme que a instrução é durável e repetível; preferência temporária deve ficar no trabalho ativo, não virar Rule.
-2. Procure por IDs e temas equivalentes em `.agents/rules/project` e nas Rules ZAIP aplicáveis antes de criar outra.
-3. Crie ou refine somente `.agents/rules/project/<nome>.md` com ID `RULE-*` único; `load` em `always`, `auto`, `file_match` ou `manual`; `priority` em `critical`, `high`, `medium` ou `low`; `max_context_tokens` positivo; `requires` com IDs existentes. Exija `globs` não vazios quando `load: file_match`.
+2. Procure por IDs e temas equivalentes em `.agents/rules/` antes de criar outra.
+3. Crie ou refine `.agents/rules/<nome>.md` com ID `RULE-*` único; `load` em `always`, `auto`, `file_match` ou `manual`; `priority` em `critical`, `high`, `medium` ou `low`; `max_context_tokens` positivo; `requires` com IDs existentes. Exija `globs` não vazios quando `load: file_match`.
 4. Escreva regras pequenas, imperativas e verificáveis; mova explicações extensas para Requirements ou documentação.
 5. Detecte contradições, ciclos de `requires`, duplicação de IDs e budgets excessivos.
 6. Rode `zaip doctor` e `zaip context validate --query "<cenário da Rule>"`; quando a orientação publicada mudar, rode `zaip adapters build` e `zaip adapters check`.
 
 ## Ownership
 
-- `.agents/rules/zaip` é fornecida pelo framework e só muda numa evolução/upgrade explícito do ZAIP.
-- `.agents/rules/project` é específica do repositório, preservada por upgrade e nunca entra no release público.
+- Rules presentes no `framework.lock.yaml` são fornecidas pelo framework e só mudam numa evolução/upgrade explícito do ZAIP.
+- Rules fora do lock são específicas do repositório, preservadas por upgrade e nunca entram no release público.
 - Não crie versões mensais ou uma Rule por Change. Edite a Rule fixa somente quando a regra real mudar; o histórico fica no Git e na Change.

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

@@ -6,12 +6,12 @@ description: Install, diagnose, migrate, upgrade, or roll back ZAIP configuratio
 # Configurar ZAIP-AIOS
 
 1. Faça dry-run, descubra a versão/layout e rejeite conflitos de checksum, ownership ou arquivos divergentes do usuário.
-2. Instale/valide `config/project.yaml`, `config/framework.lock.yaml`, as cinco Rules core em `rules/zaip`, `rules/project` preservada, todos os Requirements/skills gerenciados pelo manifest, as raízes V2 de `data` e o dashboard frontend-only em `.agents/dashboard` quando ele fizer parte da distribuição.
+2. Instale/valide `config/project.yaml`, `config/framework.lock.yaml`, as cinco Rules core diretamente em `rules/`, as Rules locais fora do lock preservadas, todos os Requirements/skills gerenciados pelo manifest, as raízes V2 de `data` e o dashboard frontend-only em `.agents/dashboard` quando ele fizer parte da distribuição.
 3. Nunca mantenha lista fixa da quantidade de Requirements ou skills no workflow; derive o catálogo do release/lock vigente.
 4. Preserve arquivos do projeto. Configuração específica usa `$zaip-skill-config`; Rules específicas usam `$zaip-skill-rules`.
 5. Mantenha raízes V1 somente leitura até migração explícita, planejada, idempotente e reversível.
 6. Rode doctor, skills, encoding, architecture, adapters e validações aplicáveis; repita o dry-run e exija ausência de drift.
-7. Em upgrade, confirme backup/rollback e não substitua `rules/project` nem escolhas de `project.yaml` silenciosamente.
+7. Em upgrade, confirme backup/rollback e não substitua Rules fora do lock nem escolhas de `project.yaml` silenciosamente.
 8. Somente no repositório-fonte do framework, após alterar arquivo gerenciado rode `pnpm sync:framework-lock` e `pnpm validate:framework-lock`; em projeto consumidor, o lock muda apenas por setup/upgrade transacional.
 
 ## Perfis Codex ZAIP-AIOS

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

@@ -1,6 +1,6 @@
 ---
 name: zaip-skill-spec
-description: Create, refine, prepare, and analyze multi-Task ZAIP delivery SPECs and DAGs while preserving draft status until the user explicitly requests ready or execution.
+description: Create, refine, prepare, and analyze technical ZAIP SPECs with complete Task DAG blueprints. Use for explicit SPEC creation or technical development/refinement; ask critical implementation questions, materialize Tasks only at ready, and execute only with state-aware authority.
 ---
 
 # Trabalhar com SPECs
@@ -16,25 +16,25 @@ SPEC é opcional para trabalho técnico amplo; Task-first continua válida para
 
 ## Create e refine
 
-1. Defina objetivo, escopo, fora de escopo, Requirements/AC, design, riscos, rollout/fallback, orçamento e perguntas bloqueantes.
-2. Antes do design técnico, leia `stack.profile` e `stack.overrides` em `.agents/config/project.yaml`, resolva `.zaip-aios/profiles/<stack.profile>.json` e considere essa a stack padrão do projeto.
-3. Registre em `implementation` o snapshot resolvido: `stack_profile`, `stack_overrides`, uma `stack_description` curta que mencione componentes e versões exatas, e `stack_components` com nome, tipo, versão exata e `version_source` workspace-relative. Nunca invente versões; use manifests, lockfiles, arquivos de runtime, imagens ou profiles verificáveis.
-4. Se vier de um PRD, mantenha `prd_id`; caso contrário, preserve a SPEC standalone sem PRD sintético.
-5. Decomponha em Tasks pequenas, verificáveis e com write scopes; modele dependências e integração na DAG.
-6. Refinar ou comparar SPECs não cria Change, Task executável, Execution nem Run.
-7. Para refine Git-native, edite somente o arquivo canônico retornado pelo create enquanto `status: draft`; preserve ID/`created_at`, incremente `revision`, atualize `updated_at` e valide com `zaip spec show <ID>`. Não use `prepare` como encerramento automático da criação. Depois de `ready`, não faça patch manual: prepare nova revisão antes da execução ou registre rework após materialização.
+1. Antes de criar, faça até cinco perguntas críticas no primeiro turno e no máximo três turnos; depois assuma decisões técnicas delegáveis com origem IA.
+2. Defina objetivo, escopo, fora de escopo, Requirements/AC, design, riscos, rollout/fallback, orçamento e perguntas bloqueantes.
+3. Leia `stack` e `stack.overrides` e registre snapshot de implementação com versões exatas e fontes verificáveis; nunca invente versões.
+4. Se vier de um PRD, mantenha `prd_id`; caso contrário, preserve a SPEC standalone.
+5. Decomponha em um blueprint técnico da própria SPEC e blueprints compactos de Tasks, verificáveis e com write scopes; dependências e paralelismo pertencem à DAG interna da SPEC. No pedido explícito de criação, use `spec create --plan`: o comando valida antes da escrita, usa criação exclusiva por arquivo e rollback compensatório em caso de falha, sem prometer transação atômica multiarquivo contra interrupção abrupta.
+6. A criação, o rework e o prepare da SPEC exigem uma Run delegada e ativa do Rafa (`zaip-agent-builder`), com propósito `execution`, sob o orquestrador do turno raiz atual; passe essa Run em `--run`, ou em `--spec-run` quando a SPEC for materializada por `prd create --plan`. Não aceite replay histórico nem a Run da Bia como autoria técnica. Não crie registros Task, Change ou Execution antes de `ready|execute`; vincule sempre a Run realmente observada e o `creation_run_id` à SPEC e agregue telemetria somente quando observada ou reconciliada.
+7. Depois de materialização, use rework rastreável e preserve snapshots/tentativas.
 
 ## Prepare
 
 1. Valide referências, cobertura de AC, IDs, ciclos, conflitos de paralelismo, comandos de verificação e o snapshot de stack contra a configuração atual do projeto.
 2. Bloqueie stack ausente, profile/overrides divergentes, versão em range ou móvel, componente sem linguagem, descrição sem componente/versão ou `version_source` inexistente. Mudança posterior da stack exige nova revisão da SPEC; não reinterprete silenciosamente snapshot preparado.
-3. Gere e valide o PreparedPlan conforme [o contrato compacto](../zaip-skill-execution/references/prepared-plan.md), então persista IDs pré-alocados sem mudar `draft` para `ready`; preparação continua em Planejamento.
+3. Gere e valide o PreparedPlan conforme [o contrato compacto](../zaip-skill-execution/references/prepared-plan.md), então persista IDs pré-alocados sem mudar `draft` para `ready`; preparação continua em Planejamento. Um pedido explícito posterior de `spec ready` materializa, na mesma operação idempotente, a DAG em Execution, Changes e Tasks `planned`, sem iniciar a execução.
 4. Quando o plano for global de um PRD, a SPEC pode ser preparada/ativada pelo pai sem duplicar outra Execution.
 5. Após `prepare`, mostre que a SPEC continua em Planejamento e pare; não encadeie `spec ready` ou `spec execute` sem a solicitação explícita correspondente.
 
 ## Handoff e analyze
 
-1. Pare em Planejamento após `prepare`. Somente após pedido explícito de promoção, use `$zaip-skill-move-spec`; somente após pedido explícito de execução, delegue a `$zaip-skill-execution`.
+1. Pare em Planejamento após `prepare`. Somente após pedido explícito de promoção, use `$zaip-skill-move-spec`: `spec ready` mantém a SPEC em `ready` e materializa a DAG sem executá-la; cada Task materializada `planned` e nunca iniciada aparece em Pronto para Executar, inclusive com `spec_id` preenchido. Somente após pedido explícito de execução, delegue a persistência da continuação, ativação e orquestração a `$zaip-skill-execution`.
 2. Considere a SPEC entregável somente quando Changes, Tasks, Executions, Runs e evidências descendentes passarem.
 3. Na análise, agregue tokens/custo por conversa, planejamento, execução e total, sem dupla contagem.
 

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

@@ -34,8 +34,8 @@ Somente trabalho executável é capturado como Task-first. Perguntas, análises
 
 ## Assurance proporcional
 
-1. Quando `assurance.version: 1` estiver ativo, Task standalone `lite` termina com exatamente uma validação tipada aprovada e exatamente uma Evidence tipada aprovada cobrindo todos os ACs. Ajustes simples de frontend podem usar esse perfil e não exigem Evidence de Definição ou Planejamento; a Evidence comprova somente a entrega e sua verificação.
-2. Task `standard` usa exatamente duas validações/Evidences no perfil base ou três no elevado; `standard_depth: auto` eleva Tasks com múltiplos write scopes. Inclua teste executado e modalidades distintas.
-3. Task `critical` usa três ou mais validações, Evidence por AC, teste, quality review por autor/Run independente, discriminação de mutação, rollback e commit final. Nunca rebaixe risco sensível para caber no perfil `lite`.
+1. Quando `assurance.version: 1` estiver ativo, Task standalone `lite` termina com ao menos uma validação tipada aprovada e uma Evidence tipada aprovada cobrindo todos os ACs; extras são aceitos. Teste só é exigido quando lógica ou regressão forem declaradas. Ajustes simples de frontend não exigem Evidence de Definição ou Planejamento; a Evidence comprova somente a entrega e sua verificação.
+2. Task `standard` usa ao menos duas validações no perfil base ou três no elevado, com modalidades distintas, teste executado e Evidence consolidada; não use quotas máximas. `standard_depth: auto` decide por sinais persistidos, não pelo número de write scopes.
+3. Task `critical` exige pelo menos três validações, Evidence consolidada e quality review independente. Exija mutação para segurança/dados críticos; lógica determinística pode escolher mutação manualmente como modalidade adicional. Exija rollback para migração, irreversibilidade ou rollback não trivial; commit final para produção, distribuição, migração ou ação externa; Evidence individual por AC somente para segurança ou migração enquanto não houver sinal persistido para outro controle. Nunca rebaixe risco sensível para caber no perfil `lite`.
 4. Quantidade não substitui semântica: cada Evidence referencia validações aprovadas da mesma Task, Change e Execution e descreve o outcome observado.
 5. Nunca encerre a Run raiz sem executar `zaip-agent-finalizer` como último Sub-Run da Execution nem com a Task em `executing` ou `verifying`. Gate insuficiente ou finalizador ausente termina a tentativa em `blocked`; retome com `task resume`. Falha técnica usa `failed` e `task rework` na mesma identidade; completed/cancelled são imutáveis.

package/templates/.agents/skills/zaip-skill-tool-setup/references/secrets.md

@@ -1,7 +1,7 @@
 # Secrets
 
 - Versione `.agents/.env.example` somente com nomes e comentarios.
-- Ignore `.agents/.env`, `.agents/.env.*`, `.agents/local/` e `.agents/secrets/`.
+- Ignore `.agents/.env`, `.agents/.env.*`, `.local/` e `.agents/secrets/`.
 - Prefira secret manager ou arquivo fora do repositorio para producao.
 - Nao peça segredo no chat, argumento de processo, log ou evidencia.
 - Valide presenca sem exibir valor; redija erros e headers.

package/templates/.agents/skills/zaip-skill-tool-setup/scripts/tool-state.mjs

@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
 import { parse, stringify } from "yaml";
 
 const [command = "list", id, field, value] = process.argv.slice(2);
-const path = resolve(".agents/local/tools-state.yaml");
+const path = resolve(".local/tools-state.yaml");
 let state = { schema_version: 1, profile: "default", tools: {} };
 try {
   state = parse(await readFile(path, "utf8"));

package/templates/.agents/skills/zaip-skill-website-readiness/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: zaip-skill-website-readiness
+description: Build capability-aware websites with discoverable agent-readable metadata.
+---
+
+# Website and Agent Readiness
+
+Use this skill for `apps/site/**`, landing pages, institutional websites, SEO, GEO,
+Markdown for Agents, or an Agent Readiness audit. Jonny owns implementation inside the
+site scope; Manu remains the owner of central design rules and must be called first when
+the work changes `DESIGN.md`, design tokens, or canonical components.
+
+## Workflow
+
+1. Read the project stack, `DESIGN.md`, design tokens, and existing central components.
+2. Identify the user journeys, canonical URLs, content hierarchy, and conversion goals.
+3. Reuse the framework site stack and central components. Do not fork the design system
+   inside the site.
+4. Implement responsive, semantic, accessible pages with deterministic metadata.
+5. Apply the capability-aware checklist in
+   [references/capability-checklist.md](references/capability-checklist.md).
+6. Verify the rendered HTML, structured data, crawler files, Markdown representation,
+   links, and response headers. Record unsupported capabilities explicitly.
+
+## Required outcomes
+
+- Landing pages and institutional pages use the configured site stack and design system.
+- Every indexable page has a canonical URL, useful title and description, semantic
+  headings, accessible navigation, and appropriate Open Graph metadata.
+- Structured data uses only facts present in the product or organization content.
+- `/robots.txt` contains valid `User-agent` groups and references the canonical sitemap.
+- `/sitemap.xml` contains only canonical, indexable URLs and is updated by the build.
+- Agent-readable Markdown is available through `Accept: text/markdown` when the hosting
+  stack supports content negotiation; otherwise publish an explicit Markdown endpoint
+  and advertise it without claiming negotiation support.
+- Link headers or HTML links advertise only resources that actually exist.
+- AI crawler rules and Content Signals reflect the product owner's policy; never infer
+  permission to train from a generic allow rule.
+
+## Capability boundary
+
+Verify only capabilities implemented by the project. Never manufacture OAuth, OIDC,
+OAuth Protected Resource metadata, `auth.md`, MCP Server Cards, Agent Skills indexes,
+WebMCP tools, DNS-AID, Web Bot Auth, x402, MPP, UCP, or ACP. A static marketing site is
+not defective merely because an inapplicable API, auth, or commerce capability is
+absent. Report each check as implemented, applicable but missing, or not applicable.
+
+## Verification
+
+Run the site's own lint, typecheck, unit, accessibility, build, and preview checks. For
+readiness, verify status code and content type for `/`, `/robots.txt`, `/sitemap.xml`,
+the Markdown request/endpoint, and each published well-known resource. Validate JSON-LD
+as JSON and inspect the rendered browser experience before declaring completion.

package/templates/.agents/skills/zaip-skill-website-readiness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: Website Readiness
+  short_description: Build agent-ready sites with truthful discovery.
+  default_prompt: Use $zaip-skill-website-readiness to implement or audit an apps/site change without inventing unavailable integrations.

package/templates/.agents/skills/zaip-skill-website-readiness/references/capability-checklist.md

@@ -0,0 +1,32 @@
+# Capability checklist
+
+Use three states for every item: `implemented`, `applicable-missing`, or
+`not-applicable`. Evidence must come from built or served artifacts.
+
+## Baseline for every public website
+
+- Semantic HTML, canonical URLs, metadata, Open Graph, accessible names, and useful
+  internal links.
+- Valid JSON-LD containing only verifiable organization, website, article, service, or
+  breadcrumb facts that match the visible content.
+- Valid `/robots.txt` with at least one `User-agent` directive, explicit policy, and a
+  canonical `Sitemap:` directive.
+- Valid `/sitemap.xml` with canonical, indexable URLs.
+- AI-specific crawler groups and `Content-Signal` directives matching the owner's
+  documented policy.
+- Agent-readable Markdown through content negotiation or a truthful advertised
+  fallback endpoint.
+- GEO content that answers user questions directly, identifies entities consistently,
+  cites first-party facts, and does not hide critical content behind client-only UI.
+
+## Publish only when implemented
+
+- RFC 8288 Link headers for real API catalogs, service documentation, alternate
+  Markdown, or other existing resources.
+- `/.well-known/api-catalog` for a real API.
+- OAuth/OIDC and OAuth Protected Resource metadata for a real protected API.
+- `/auth.md` only when agent registration is implemented.
+- MCP Server Cards, Agent Skills indexes, WebMCP tools, DNS-AID, Web Bot Auth, or
+  agentic commerce discovery only when their corresponding runtime exists.
+
+Never create placeholder discovery documents merely to increase an audit score.

package/templates/.agents/tools/catalog.yaml

@@ -44,12 +44,6 @@ tools:
     name: "PostgreSQL"
     status: example
     manifest: mcp/development/postgresql/manifest.yaml
-  - id: sqlite
-    type: mcp
-    category: development
-    name: "SQLite"
-    status: example
-    manifest: mcp/development/sqlite/manifest.yaml
   - id: slack
     type: mcp
     category: development

package/templates/.agents/zaip-aios/README.md

@@ -10,4 +10,4 @@ Documentacao operacional local do ZAIP-AIOS para pessoas e agentes.
 4. Nao carregue toda esta pasta no contexto.
 
 `VERSION` informa a versao do handbook instalada. As regras canonicas continuam em
-`.agents/rules/zaip/`; este handbook explica como aplica-las, mas nao as substitui.
+`.agents/rules/`; este handbook explica como aplica-las, mas nao as substitui.

package/templates/.agents/zaip-aios/guides/01-primeiros-passos.md

@@ -1,10 +1,12 @@
 # Primeiros passos
 
-1. Leia `.agents/config/project.yaml` e `.agents/rules/zaip/core.md`.
-2. Consulte `.agents/projections/runtime/` para descobrir o estado atual.
+1. Leia `.agents/config/project.yaml` e `.agents/rules/core.md`.
+2. Consulte `.agents/records/lifecycle/` para descobrir o estado atual pelos manifests canônicos.
 3. Classifique a entrada: Conversation, Task avulsa, SPEC ou PRD. Pergunta/análise read-only é Conversation e não cria Task.
 4. Carregue somente Rules, Requirements e skills aplicaveis.
 5. Defina aceite verificavel antes de editar.
 6. Antes de escrita persistente, inicie Task, Change, Execution e Run raiz do orquestrador; execute Sub-Runs, teste e registre evidencias no ciclo de vida ativo.
 
 Evite varrer `.agents/records/`: abra um record apenas quando possuir seu ID.
+
+Para PRD/SPEC, diferencie conversa de criação: “me ajude a pensar” não cria artefato; “crie” persiste o pacote `draft` completo e sua telemetria. Faça até cinco perguntas críticas por turno, no máximo três turnos; depois registre decisões delegáveis da IA. Tasks reais só nascem em `ready|execute`.

package/templates/.agents/zaip-aios/guides/03-tasks.md

@@ -10,3 +10,9 @@ Use Task para uma entrega pequena, independente e com um resultado claro.
 6. Use uma Run raiz do orquestrador por tentativa, finalize os Sub-Runs de trabalho e execute o finalizador como ultimo filho.
 7. Antes de a Run terminar, mova a Task para completed, blocked, failed ou cancelled; nunca deixe executing/verifying.
 8. Retome blocked com `task resume`; trate failed com `task rework` na mesma Task. Completed/cancelled sao imutaveis.
+
+Em PRD/SPEC `draft`, a lista visível vem dos blueprints do PreparedPlan e não representa Tasks materializadas. `ready` cria os registros `planned`. Execução pode ser pedida diretamente no menor grão Task, sem ampliar para toda a SPEC ou PRD.
+
+## Modelo, effort e velocidade
+
+Conversation e Task-first preservam o modelo, o reasoning effort e a velocidade selecionados manualmente no Codex. A única forma suportada de executar trabalho de produto mais rápido é usar Fast manualmente em uma Task-first realmente independente; o ZAIP não ativa nem persiste essa seleção. Uma Task descendente de PRD ou SPEC segue a orquestração automática do pai e executa sempre com velocidade `standard`, mesmo quando for acionada no menor grão.

package/templates/.agents/zaip-aios/guides/04-specs.md

@@ -2,10 +2,10 @@
 
 Use SPEC quando a entrega exige varias Tasks ou uma ordem de dependencia.
 
-1. Transforme o resultado desejado em capacidades verificaveis.
-2. Consulte `stack.profile` e `stack.overrides` em `.agents/config/project.yaml` e resolva `.zaip-aios/profiles/<stack.profile>.json` como stack padrao do projeto.
+1. Transforme o resultado desejado em capacidades verificaveis. Faça até cinco perguntas críticas por turno e encerre esclarecimento em até três turnos.
+2. Consulte `stack` e `stack.overrides` em `.agents/config/project.yaml`; este arquivo contem a definicao tecnica canonica da stack do projeto.
 3. Registre `stack_profile`, `stack_overrides`, `stack_description` curta e componentes com linguagem, runtime, frameworks, versoes exatas e fontes verificaveis no workspace.
-4. Divida em Tasks pequenas, cada uma com aceite proprio.
+4. Registre o blueprint técnico da SPEC e divida em blueprints de Tasks pequenas, cada uma com aceite próprio; `spec create --plan` persiste esse pacote em `draft` e registros Task só são criados em `ready|execute`.
 5. Modele dependencias como DAG; evite sequencias artificiais.
 6. Identifique caminhos criticos, riscos e rollback.
 7. Mapeie cada Requirement para Tasks e evidencias.
@@ -14,3 +14,7 @@ Use SPEC quando a entrega exige varias Tasks ou uma ordem de dependencia.
 10. Depois de todas as Tasks concluidas, rode verificacao e Evidence parentais antes de deliver.
 
 Uma SPEC planeja a entrega; nao autoriza mudancas externas por si so.
+
+Use uma SPEC por padrão. Separe outra somente quando as capacidades puderem ser implementadas e verificadas em paralelo contra contratos estáveis, sem dependência ou write scope conflitante. Dependências e ordem ficam na DAG de Tasks da mesma SPEC.
+
+Toda Execution originada por SPEC usa velocidade `standard` em suas Tasks, Runs e Sub-Runs. A seleção manual de Fast no Codex não substitui essa política. Se uma necessidade urgente for realmente pequena e independente da DAG e dos gates parentais, ela pode ser tratada como Task-first com velocidade manual; não fragmente uma SPEC artificialmente apenas para executar mais rápido.