@zaip-ai/cli 1.3.8 → 1.4.1

package/templates/.agents/runtime/checksums.sha256

@@ -1,11 +1,11 @@
 b146bd0c7c60b1ab43c4f71e0b1d2262c6df6da6f7053a0425f834ccb77a6b48  LICENSE
 bc02cba77e8d51e5c580f43668863dc868eda66f1ff663bfaa49fcf3ca16320e  THIRD_PARTY_NOTICES.md
 64d23f858ef51b0f996e4966d4e27c0371b437e2d2787890b1f7ad22d4ec5663  VERSION
-04b70f890aceaf3b1d0409e4446cd4315aa9ac24056b1abd9813d07444e212f7  bin/zaip.mjs
+09e8f6c1c5de52685f76c99301b4af83b78e3cbd30c4ab5495d1c8a33af22693  bin/zaip.mjs
 bed6ab1fda844209edc628c2a675021ad6acb9a2f7ecb7ae017b5a916712da24  manifest.json
 7f89219d7c567c82a51679ad136d84364bded7ac659492537e125d33b1d58a7a  migrations/001-layout-v1.json
 5f8c48b286d0b44d8fbb57a9a5d009a8a500439aa3148d750b8f193f72995c9f  migrations/002-layout-v2.json
 182a587dca8080f732cb387dbdeff4c12034a4a116efe35b4cd3c1c0a21ad10b  pnpm-lock.sha256
-d5e403c33b3aa09c15601e652dd1a54d345d56e6df3259baee74e94db97f3486  provenance.json
+82f3eadf48498933aa6ccb00432070ede8129f983c40a9da697c6ffaf9a76a20  provenance.json
 4669f375688be830958d45269bb0f8dfe65daf8db677f72728c15dc89d42d820  sbom.cdx.json
 b3ffedf9e146be802a15b4009f33e031dec3071ca1525e12c67606fd964a3067  schemas/contracts.schema.json

package/templates/.agents/runtime/provenance.json

@@ -6,6 +6,6 @@
   "source_origin": "zaip-aios:local-build",
   "lockfile_sha256": "382ebb27a2a951eb61280171c27116233762370d9093ab516caef216475ba4fc",
   "sbom_sha256": "4669f375688be830958d45269bb0f8dfe65daf8db677f72728c15dc89d42d820",
-  "runtime_sha256": "270477b37c53af87a1f0e872ebdb7bc49c8c4e45bfec866086d9ad6e9d4d666c",
-  "statement_sha256": "499227a810d2667f64d5a2eb51dd047e08b9a44d041fdb6bcc864093aa10f760"
+  "runtime_sha256": "0ea51822ffd133866110c2c37ff644952ce62c4899b53ae5827ad59406a57e24",
+  "statement_sha256": "d2342722cd5b397a93cb64136e808d35e5300f1d5ceb6cf90e3e22c0565f9a53"
 }

package/templates/.agents/skills/zaip-skill-api-to-mcp/SKILL.md

@@ -16,4 +16,8 @@ description: Design, scaffold, secure, test, and register a ZAIP-maintained MCP
 9. Implemente testes offline com fixtures sanitizadas, contratos de schema, erros, autorizacao e resistencia a prompt injection em dados remotos.
 10. Registre no catálogo como `disabled`; use `$zaip-skill-tool-setup` para configurar o Codex e fazer smoke test read-only.
 
+## Contrato mínimo Codex MCP
+
+Todo servidor MCP criado do zero deve concluir o handshake `initialize` com instruções claras e capacidades declaradas antes de expor ferramentas. Implemente `tools/list` com nomes estáveis, descrição e schemas de entrada fechados; `tools/call` deve validar a entrada, aplicar a política de aprovação e responder em formato MCP, inclusive em erros. Para stdio, escreva exclusivamente mensagens JSON-RPC no stdout e envie logs, diagnóstico e progresso para stderr. Nunca escreva banners, texto livre ou segredos no stdout.
+
 Leia `references/security-contract.md` antes de implementar e `references/server-layout.md` ao criar arquivos.

package/templates/.agents/skills/zaip-skill-brand-governance/SKILL.md

@@ -5,18 +5,34 @@ description: Define and govern an evidence-backed brand platform, Brandbook, arc
 
 # Governar a marca
 
-## Localização canônica
+## Artefatos e localização canônica
 
-Salve Brandbooks, plataformas de marca, decisões de identidade, arquétipos, escalas de diferencial semântico e materiais de governança em `.agents/branding/`. Todo Brandbook salvo como `.docx` deve ter, na mesma pasta e com o mesmo nome-base, uma fonte canônica `.md` com o conteúdo estratégico equivalente; mantenha os dois arquivos sincronizados a cada revisão. Use `.agents/branding/archive/` somente para versões substituídas. Não crie esses artefatos em `docs/`, na raiz do repositório ou em diretórios de outra disciplina.
+Salve plataformas de marca, Brandbooks, decisões de identidade, arquétipos, escalas de diferencial semântico e materiais de governança em `.agents/branding/`. Use `.agents/branding/archive/` somente para versões substituídas. Não crie esses artefatos em `docs/`, na raiz do repositório ou em diretórios de outra disciplina.
 
-O arquivo central da área é `.agents/branding/brandbook.md`; atualize-o quando a decisão afetar a plataforma de marca. A versão Word correspondente é `.agents/branding/brandbook.docx`.
+Há dois artefatos distintos:
 
-1. Delimite objetivo, públicos, contexto de negócio, fontes e autoridade de aprovação. Classifique cada afirmação como evidência, hipótese ou decisão; não apresente hipótese como fato.
-2. Construa ou atualize a plataforma: cultura, propósito, posicionamento, proposta de valor, promessa, diferenciais, atributos, personalidade, arquitetura de marca e pontos de contato. Para Brandbooks completos, use o framework de domínios em [referências do Brandbook](references/brandbook-framework.md).
-3. Quando o trabalho incluir um Brandbook, mantenha uma fonte estratégica interna e derive uma versão externa somente com conteúdo autorizado. Preserve versão, proprietário, aprovadores, confidencialidade e histórico de decisão.
+- A plataforma de marca progressiva é a base estratégica em Markdown, normalmente `.agents/branding/brand-platform.md`. Ela registra a descoberta e as decisões de propósito, posicionamento, arquitetura e identidade à medida que amadurecem. Não exige DOCX e não deve ser apresentada como um Brandbook completo.
+- O Brandbook consolidado é o artefato oficial, completo e versionado. Sua fonte canônica é `.agents/branding/brandbook.md` e a versão Word correspondente é `.agents/branding/brandbook.docx`. Todo Brandbook salvo como `.docx` deve ter, na mesma pasta e com o mesmo nome-base, uma fonte `.md` estrategicamente equivalente; mantenha os dois sincronizados a cada revisão.
+
+## Descoberta antes da consolidação
+
+1. Antes de criar um Brandbook do zero, faça perguntas críticas sobre objetivo, ICP e públicos, contexto de negócio, oferta, proposta de valor, diferenciais, arquitetura de marca e, quando relevante, a relação entre marca-mãe, produtos e portfólio, autoridade de aprovação e fontes disponíveis. Faça no máximo cinco perguntas por turno e no máximo três turnos de descoberta; espere as respostas sem preencher decisões abertas. Ao encerrar esse limite, registre suposições delegáveis como hipóteses, nunca como aprovação ou fato.
+2. Construa primeiro a plataforma de marca progressiva: cultura, propósito, posicionamento, proposta de valor, promessa, diferenciais, atributos, personalidade, arquitetura e pontos de contato. Classifique cada afirmação como evidência, hipótese ou decisão; não apresente hipótese como fato.
+3. Só consolide um Brandbook completo quando ele for solicitado e a plataforma tiver base suficiente para os domínios aplicáveis. Não preencha lacunas materiais com afirmações inventadas: mantenha-as como hipótese, pendência ou pergunta. Se já existir Brandbook aprovado, preserve-o durante a descoberta e altere somente decisões expressamente autorizadas.
+
+## Referências fornecidas
+
+Quando o pedido trouxer ou pedir o uso de referências — texto, arquivo, site, PDF, apresentação, imagem ou outro material acessível — extraia delas uma base de trabalho antes de repetir perguntas já respondidas. Para cada contribuição relevante, preserve fonte, locator ou página quando disponível, data quando conhecida e classificação como evidência, hipótese ou decisão.
+
+Use as referências para montar ou enriquecer a plataforma e pergunte somente pelas lacunas materiais para a decisão solicitada. Quando o pedido autorizar expressamente a consolidação e as referências sustentarem a base necessária, não exija uma pergunta adicional de aprovação. Uma referência não equivale a aprovação, autorização de publicação ou prova de titularidade. Conteúdo de terceiros serve como fonte, síntese ou referência metodológica; não o copie como conteúdo da marca.
+
+## Consolidação e governança
+
+1. Para Brandbooks completos, use o framework de domínios em [referências do Brandbook](references/brandbook-framework.md). Mantenha uma fonte estratégica interna e derive uma versão externa somente com conteúdo autorizado. Preserve versão, proprietário, aprovadores, confidencialidade e histórico de decisão.
    - A primeira versão oficial de um Brandbook é sempre `v1.0`; não use versões `v0.x`. Incrementos posteriores seguem versionamento semântico editorial (`v1.1`, `v1.2` para evolução aprovada; `v2.0` para mudança material de plataforma ou arquitetura).
-4. Para arquétipos, registre evidência, comportamento esperado, limites e implicações para linguagem e experiência. Se houver pesos, valide que o total é 100%; se não houver pesquisa, registre como hipótese de trabalho.
-5. Para diferencial semântico, registre dimensões, polos, escala, fonte, data, amostra e diferença entre identidade desejada e percebida. Não fabrique respostas, baseline, validação estatística ou brand equity.
-6. Encaminhe aplicação ordinária de Brandbook aprovado, campanhas, copy e ativos para Lúcia; scripts e playbooks sales-facing para Aaron; análise quantitativa para Gabi; impacto de receita/custo e RevOps para Robert; e produção operacional genérica para Clara. Um Brandbook aprovado é input, não motivo para assumir a aplicação.
+2. Para arquétipos, registre evidência, comportamento esperado, limites e implicações para linguagem e experiência. Se houver pesos, valide que o total é 100%; se não houver pesquisa, registre como hipótese de trabalho.
+3. Para diferencial semântico, registre dimensões, polos, escala, fonte, data, amostra e diferença entre identidade desejada e percebida. Não fabrique respostas, baseline, validação estatística ou brand equity.
+4. Encaminhe aplicação ordinária de Brandbook aprovado, campanhas, copy e ativos para Lúcia; scripts e playbooks sales-facing para Aaron; análise quantitativa para Gabi; impacto de receita/custo e RevOps para Robert; e produção operacional genérica para Clara. Um Brandbook aprovado é input, não motivo para assumir a aplicação.
+5. Não gere imagens, mockups ou outros ativos visuais sem solicitação explícita.
 
 Consulte [padrões de Brandbook](references/brandbook-standards.md) e o [framework de domínios](references/brandbook-framework.md) ao estruturar entregáveis internos ou externos.

package/templates/.agents/skills/zaip-skill-brand-governance/references/brandbook-framework.md

@@ -1,6 +1,6 @@
 # Framework de domínios do Brandbook
 
-Use este framework para um Brandbook interno. Ele organiza a estratégia; não autoriza apresentar hipóteses como fato nem copiar o conteúdo de uma referência externa.
+Use este framework somente para um Brandbook interno consolidado. A plataforma de marca progressiva antecede esse artefato e permanece em Markdown, sem obrigação de DOCX. O framework organiza a estratégia; não autoriza apresentar hipóteses como fato nem copiar o conteúdo de uma referência externa.
 
 ## Versionamento
 
@@ -8,7 +8,7 @@ Inicie todo Brandbook aprovado em `v1.0`. Use `v1.x` para complementos ou revis
 
 ## Formatos canônicos
 
-Para cada Brandbook, mantenha obrigatoriamente uma fonte estratégica em Markdown e uma versão Word com o mesmo nome-base na pasta `.agents/branding/`; por exemplo, `Brandbook v1.0.md` e `Brandbook v1.0.docx`. Atualize ambos na mesma alteração. O Markdown é a fonte de revisão Git-native; o DOCX é a versão de leitura e apresentação.
+Para cada Brandbook, mantenha obrigatoriamente uma fonte estratégica em Markdown e uma versão Word com o mesmo nome-base na pasta `.agents/branding/`; por exemplo, `Brandbook v1.0.md` e `Brandbook v1.0.docx`. Atualize ambos na mesma alteração. O Markdown é a fonte de revisão Git-native; o DOCX é a versão de leitura e apresentação. Não aplique essa exigência à plataforma de marca progressiva.
 
 ## Fundação
 

package/templates/.agents/skills/zaip-skill-brand-governance/references/brandbook-standards.md

@@ -1,6 +1,6 @@
 # Padrões de Brandbook e governança
 
-Use este roteiro quando o pedido exigir a plataforma ou o Brandbook da marca.
+Use este roteiro quando o pedido exigir a plataforma ou o Brandbook da marca. Comece pelo diagnóstico e pela plataforma de marca progressiva; ela não é um Brandbook completo e não exige versão Word. Um Brandbook consolidado só é produzido quando solicitado e depois de haver base estratégica suficiente ou referências que a sustentem.
 
 ## Fonte estratégica interna
 
@@ -8,7 +8,7 @@ Registre os treze domínios: cultura da empresa e da marca; posicionamento e pla
 
 O Brandbook também registra controle do documento; história; mercado; público e personas; promessa e diferenciais; DNA, atributos e personalidade; tom de voz; arquitetura; identidade verbal e visual; evidências e decisões.
 
-Cada decisão material deve informar proprietário, aprovador, versão, data, evidência e classificação de confidencialidade. Conteúdo proprietário de terceiros serve como referência metodológica, nunca como conteúdo reutilizável.
+Cada decisão material deve informar proprietário, aprovador, versão, data, evidência e classificação de confidencialidade. Referências fornecidas podem sustentar a plataforma quando forem extraídas com fonte e locator; elas não constituem aprovação nem autorização de publicação. Conteúdo proprietário de terceiros serve como referência metodológica, nunca como conteúdo reutilizável.
 
 ## Versão externa
 

package/templates/.agents/skills/zaip-skill-change/references/observable-evidence.md

@@ -74,6 +74,21 @@ zaip evidence record --id EVD-CENARIO --task TASK-ID --summary "alcance comprova
 
 O JSON usa `schema_version: 1`, `id`, `task_id`, `change_id`, `execution_id`, `run_id`, `acceptance_ids`, `proof_kind`, `state`, `scenario`, `expected`, `observed`, `observed_at`, `examiner_id`, `commit_sha`, `candidate_version`, `environment`, `visual`, `correlation_ids`, `locators`, `limitations`, `not_applicable_reason`, `pending_reason`, `dependency`, `resume_plan` e `attempts`. Consulte o schema e os exemplos testados em `packages/specs/src/assurance/artifacts.ts` e `assurance-contract.test.ts`; não invente campos V2. A versão candidata identifica o artefato efetivamente observado; o SHA Git continua sendo o vínculo exigido pelo assurance.
 
+## Preservar a captura local antes de referenciá-la
+
+Quando uma captura real selecionada já foi examinada, preserve o arquivo temporário antes de usar seu locator na observação. O fluxo local copia exclusivamente uma imagem regular `.png`, `.jpg`, `.jpeg` ou `.webp`, sem seguir symlinks, para um caminho ignorado pelo Git e protegido contra substituição:
+
+```text
+zaip evidence screenshot preserve --source ABSOLUTE_IMAGE --change CHG-ID --task TASK-ID --run RUN-ID --scenario rota-ou-cenario --state estado-observado --examined-by AGENT-OU-PESSOA --observed-at ISO-8601 --json
+zaip evidence screenshot verify --evidence .local/evidences/c-HASH/t-HASH/r-HASH/rota-ou-cenario--estado-observado.png --json
+```
+
+O resultado fornece locators relativos em `.local/evidences/c-<hash>/t-<hash>/r-<hash>/`, mantendo os IDs completos CHG/TASK/RUN/EXEC somente no sidecar de cada extensão (`.png.evidence.json`, por exemplo), junto ao SHA-256, bytes, examinador e horário observado. Os nomes de cenário e estado são slugs minúsculos Windows-safe de até 32 caracteres; o destino completo tem limite de 240 caracteres. Um destino existente falha e nunca é sobrescrito. Quando ausente, o comando cria somente o marcador `.local/.gitignore` com `*` e `!.gitignore`; se ele já existir, exige exatamente esse conteúdo e não o reescreve. A fonte pode permanecer temporária ou ser descartada somente depois da preservação e da verificação bem-sucedida.
+
+O marcador existente aceita finais de linha LF ou CRLF, sem reescrita. `.local/evidences/` é histórico local persistente: não deve participar da limpeza de temporários ou caches. Capturas exploratórias continuam em `.temp` ou no temporário da ferramenta; somente as selecionadas e examinadas são preservadas. As imagens não acompanham clones do Git e precisam de backup local independente quando sua retenção for necessária.
+
+Esse comando não abre uma UI, não certifica a origem da imagem, não examina pixels e não substitui `validation observe`, Validation ou Evidence. Registre URL, viewport, versão carregada, expectativa, resultado e limitações na observação; indique somente o locator preservado. Screenshot e hash sozinhos continuam insuficientes para provar comportamento, integração ou aprovação.
+
 `environment` descreve classe, identificador e versão. Estado `confirmed` exige versões observadas do candidato e do ambiente; sem elas, registre limitação/pendência, não um valor presumido. Integração confirmada exige `correlation_ids` do cenário; API ou persistência isoladas não exigem correlação artificial. Prova visual confirmada também exige `visual.url`, `viewport` no formato `1366x768`, `captured_at`, `loaded_version` igual a `candidate_version` e `examination`. Use URL base sem credenciais, query ou fragmento; registre filtros e estado relevantes no cenário sanitizado, nunca tokens de acesso. Preencha indisponibilidade com `null` nos campos permitidos, sem atribuir uma observação inexistente a produção.
 
 `validation record` também admite `failed` e `not_applicable` (este exige `--reason`); esses registros não alimentam Evidence aprovada. Informe `--executed-at` e `--asserted-outcome` nas novas entregas. A omissão desses campos conserva o comportamento legado e não demonstra que a CLI executou um teste naquele horário. Pendência de ferramenta usa `validation observe`, não `failed` de produto.

package/templates/.agents/skills/zaip-skill-dashboard-sqlite/SKILL.md

@@ -3,12 +3,18 @@ name: zaip-skill-dashboard-sqlite
 description: Rebuild and open the isolated SQLite dashboard comparison runtime.
 ---
 
-# Dashboard SQLite comparativo
+# Dashboard SQLite persistente
 
-Use esta skill para o dashboard SQLite em `.agents/dashboard`. Ela reconstrói um snapshot descartável
-em `.local/dashboard-sqlite/read-model.sqlite`.
+Use esta skill para o dashboard SQLite em `.agents/dashboard`. `.local/sqlite/` é o diretório
+central por workspace para bancos SQLite gerenciados localmente; vários nomes estáveis podem ser
+legítimos conforme seu propósito. O Dashboard usa exatamente
+`.local/sqlite/zaip-aios-dashboard.sqlite`. Nunca crie cópias do Dashboard por porta, PID, hash
+ou geração. WAL, SHM e JOURNAL são auxiliares normais do banco aberto. Fixtures descartáveis ficam
+em `.local/sqlite/tests/<fixture>/` com limpeza automática. Workspaces isolados usam sua própria
+`.local/sqlite/`; bancos internos de ferramentas externas seguem o armazenamento dessas ferramentas.
 
-1. Na raiz do repositório, execute `node .agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs`.
+1. Prefira abrir o launcher: ele usa o banco existente e sincroniza os canônicos em segundo plano.
+   Para sincronização manual sem outro writer, execute `node .agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs`.
 2. Para regenerar os artefatos sem depender dos globs do workspace principal, execute
    `node .agents/dashboard/packages/local-runtime/scripts/build-sqlite-dashboard.mjs`.
 3. Verifique a paridade de all-time/intervalos, zero conhecido e todo-desconhecido/null com
@@ -22,4 +28,6 @@ O banco é um read model dos registros e da configuração ZAIP. `daily_aggregat
 read model lifecycle diário e alimenta, via SQL, os fatos de primeiro fold de
 `operations?scope=quick` e `cost-monitor?scope=summary` (runs, tokens, custo e cobertura).
 A duração híbrida legada e os detalhes de entidades permanecem no projection/adapter compartilhado
-para preservar semântica. A API é somente leitura para que o snapshot não fique desatualizado.
+para preservar semântica. Comandos suportados pela API gravam nos canônicos e renovam a projeção.
+Valide `snapshot_state: current` após a sincronização, além da integridade do banco. Os auxiliares
+WAL/SHM/JOURNAL são transacionais; não os trate como versões obsoletas nem os apague com banco aberto.

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

@@ -5,11 +5,16 @@ description: Analyze bounded datasets, diagnose metrics, and produce reproducibl
 
 # Analisar dados delimitados
 
-1. Confirmar o dataset, período, unidade de análise, definições de métrica e decisão que a análise deve informar. Quando qualquer insumo não estiver disponível, registrar a limitação e não preencher a lacuna com suposição.
-2. Inspecionar a qualidade antes da conclusão: cobertura, duplicidade, nulos, granularidade, filtros e proveniência. Separar dado observado, derivação determinística e inferência.
-3. Declarar método reproduzível: arquivos ou fontes usados, filtros, transformações, agregações, fórmula e intervalo temporal. Executar checks ou testes proporcionais quando houver código analítico.
-4. Reportar achados com incerteza, exceções e limites. Não converter indisponibilidade em zero, causalidade ou certeza; distinguir descrição, comparação e hipótese.
-5. Produzir evidência vinculada aos Acceptance Criteria e retornar somente resultados sustentados pelo dataset delimitado. Escalar alterações de produto, dashboard ou esquema para o executor apropriado.
+## Descoberta e entrega progressivas
+
+1. Comece pelos datasets e referências acessíveis fornecidos — tabela, planilha, texto, site, PDF, PPT, arquivo ou imagem. Registre fonte, locator e classificação: dado observado, definição aprovada, derivação determinística, hipótese ou lacuna. Preserve datasets e artefatos aprovados; não invente datasets, métricas ou decisões.
+2. Se o trabalho começar do zero ou o contexto for insuficiente, faça no máximo cinco perguntas críticas por turno, por até três turnos. Pergunte somente pelo briefing material: dataset, período, unidade de análise, definição de métrica e decisão que a análise deve informar. Espere as respostas antes de avançar nas partes que delas dependem; silêncio não é resposta nem aprovação. Após três turnos, registre a limitação e use somente hipóteses delegáveis, sem preencher lacunas ou inventar dados, métricas ou autoridade.
+3. Uma consulta bem delimitada com dataset, métrica e período suficientes deve ser respondida diretamente, sem questionário obrigatório ou plano analítico amplo.
+4. Aplique somente as partes necessárias ao escopo solicitado: `briefing` → `qualidade` → `análise` → `síntese`. Use Markdown para registrar briefing e síntese quando útil, sem substituir notebook, planilha ou outro formato solicitado. Identifique a análise em construção e consolide somente achados sustentados; mantenha a fonte central de dados e o artefato analítico central, referenciando-os em vez de duplicar tabelas, definições ou resultados.
+5. Inspecione a qualidade antes da conclusão: cobertura, duplicidade, nulos, granularidade, filtros e proveniência. Separe dado observado, derivação determinística e inferência.
+6. Declare método reproduzível: arquivos ou fontes usados, filtros, transformações, agregações, fórmula e intervalo temporal. Execute checks ou testes proporcionais quando houver código analítico.
+7. Reporte achados com incerteza, exceções e limites. Não converta indisponibilidade em zero, causalidade ou certeza; diferencie descrição, comparação e hipótese.
+8. Produza evidência vinculada aos Acceptance Criteria e retorne somente resultados sustentados pelo dataset delimitado. Escale alterações de produto, dashboard ou esquema para o executor apropriado.
 
 ## Casos de análise
 

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

@@ -18,10 +18,11 @@ Use esta skill somente quando o usuário pedir execução. `prepare` não autori
 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.
 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. 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`.
-13. 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.
-14. 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. “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.
+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.
+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.
 
 ## Paralelismo
 

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

@@ -13,9 +13,10 @@ description: Create and validate hidden Windows launchers for reliable local fro
    `packages/windows-launcher`; não crie backend somente para servir arquivos estáticos.
 4. Sirva somente em loopback. Use porta preferencial configurável, busca limitada e health endpoint
    com identidade do workspace.
-5. Persista sessão sanitizada no diretório temporário, isolada por hash do workspace. Sob lock
-   atômico, reutilize primeiro a sessão saudável e depois procure um runtime órfão reconhecível;
-   abra nova porta apenas quando nenhum deles existir.
+5. Persista sessão sanitizada no diretório temporário, isolada por hash do workspace. O clique mais
+   recente deve vencer: use claim serializada, encerre e confirme o launcher/runtime anterior
+   reconhecido antes de criar o novo writer; se não puder encerrar, bloqueie a abertura. O navegador
+   comanda a vida da sessão por conexão SSE, com grace para reload/BFCache.
 6. Use `.agents/config/src/icon_zaip.png` como fonte canônica padrão em workspaces ZAIP, salvo
    identidade explicitamente definida pelo projeto. Valide formato e proporção, gere o `.ico`
    temporário e compile com `/win32icon`; não mantenha cópias derivadas sem necessidade.

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

@@ -20,8 +20,10 @@
 - Bind somente em `127.0.0.1`; nunca exponha em `0.0.0.0`.
 - Use health endpoint exclusivo com `kind` e hash estável do workspace.
 - Grave `workspace`, `workspaceKey`, `rootPid`, `port` e `createdAt` no diretório temporário.
-- Crie lock por operação atômica de filesystem, com timeout e recuperação de lock obsoleto.
-- Dentro do lock, valide a sessão e procure health compatível na faixa limitada antes de iniciar.
+- Crie claim-lock curto e operação atômica para transferir ownership; o último clique encerra e
+  confirma o launcher/runtime anterior reconhecido antes de iniciar outro writer.
+- Valide o PID como launcher próprio antes de encerrá-lo; falha no encerramento bloqueia a abertura.
+- Use uma conexão SSE do navegador como lease da sessão, com grace suficiente para reload/BFCache.
 - Não considere uma porta ocupada como runtime próprio sem validar o marcador e o workspace.
 - Sirva somente arquivos dentro do build root, rejeitando URL malformada e path traversal.
 - Abra o navegador apenas após listen e sessão persistida; rotas hash podem ser abertas diretamente.
@@ -33,6 +35,6 @@
    genérico.
 2. Testes do servidor e do boundary de arquivos passam.
 3. Uma porta preferencial ocupada por outro processo é ignorada sem encerrá-lo.
-4. Dois disparos do executável mantêm o mesmo `rootPid` e a mesma `port`.
+4. Dois disparos do executável deixam somente o `rootPid`/porta do segundo clique ativos.
 5. Existe somente um processo do runtime para o workspace.
 6. O artefato distribuído funciona em path com espaços e em instalação limpa.

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

@@ -53,10 +53,10 @@ The conversation and terminal deploy report are the authority record for Git-onl
 
 ## Prove folder-scoped SSH first
 
-From the repository root, select the explicit remote or `origin`, then run once:
+From the repository root, read `.agents/config/project.yaml` immediately before deployment. Resolve `deploy.branch`; use `main` only when the file or key is absent. A malformed existing file or invalid branch is a terminal preflight failure. Never infer a target from the checked-out or upstream branch. Select the requested remote (default `origin`), then run once:
 
 ```powershell
-node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin --branch demo
+node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --remote origin
 ```
 
 The preflight must prove that the push URL uses SSH, no process override is active, the effective `core.sshCommand` comes from repository-local or matching folder configuration, its private key exists, Git identity exists, and `git ls-remote` succeeds.
@@ -75,7 +75,7 @@ Run preflight once at the start of the authorized deployment. On failure, stop.
 
 ## Synchronize and publish each cycle
 
-Fetch the selected remote and current branch once per publication cycle, without SSH overrides. Compute ahead/behind against the fetched ref. When local is behind or diverged, apply the recorded bounded reconciliation strategy and continue after successful verification; stop only if it cannot be completed safely within the bounded repair cycles. Never reset or force.
+Fetch the selected remote and configured branch once per publication cycle, without SSH overrides. Compute ahead/behind against `<selected remote>/<configured branch>`. When local is behind or diverged, apply the recorded bounded reconciliation strategy and continue after successful verification; stop only if it cannot be completed safely within the bounded repair cycles. Never reset or force.
 
 Commits created during Task execution use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>`: the effective executing-agent prefix followed by compact lineage.
 
@@ -84,14 +84,14 @@ Commits created during Task execution use `[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:X
 
 The effective provider is exclusively `CODEX` or `CLAUDE`; `AUTO` is not part of a Task subject. P/S/T blocks are emitted only when their evidence exists; a Task with no PRD or SPEC uses `[Task-first:XXXX]`, and an unattributed functional commit uses `[CODEX] <functional title>` without `ZAIP-Task`. The subject remains ≤96 characters and only its title may truncate at a word boundary. Complete available PRD, SPEC, Task, Change, and Execution IDs remain in `ZAIP-*` trailers. An explicit deploy may create only its evidenced functional commits, without broad staging, force, destructive reset, or squashing.
 
-Push once per publication cycle. With an upstream, use `git push`; for first publication, use `git push -u <remote> <branch>`. If there is no unpushed commit after the bounded reconciliation and functional-commit review, report a no-op.
+Immediately before push, re-read the target with `node .agents/skills/zaip-skill-github-deploy/scripts/preflight.mjs --repository . --resolve-branch`. If it changed since preflight, restart validation and synchronization for the new target. Push once per publication cycle with the explicit configured refspec: `git push <remote> HEAD:refs/heads/<configured branch>`. Do not use a bare `git push` or infer a target from upstream. If there is no unpushed commit after the bounded reconciliation and functional-commit review, report a no-op.
 
 - If push fails, treat it as terminal unless repository content caused a documented server-side rejection that can be repaired locally.
 - Never switch keys, accounts, remotes, or transport, and never pass SSH/config overrides or force options.
 
 ## Verify and monitor GitHub checks
 
-1. After every push, compare `git rev-parse HEAD` with one `git ls-remote <remote> refs/heads/<branch>` result.
+1. After every push, compare `git rev-parse HEAD` with one `git ls-remote <remote> refs/heads/<configured branch>` result.
 2. Inspect required GitHub checks for that exact commit using an available authenticated GitHub CLI, API, connector, or browser session. Wait up to 20 minutes for terminal status and provide a concise progress update at least once per minute.
 3. If all required checks pass, confirm the remote hash, commit title, SSH identity source, key path, and worktree status.
 4. If a check fails, read the exact job and step logs before editing. Do not weaken or remove the check merely to obtain green status.

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

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { parseDocument } from "./yaml-parser.mjs";
 
 const options = parseArguments(process.argv.slice(2));
 
@@ -11,11 +12,24 @@ try {
   const requestedRepository = resolve(options.repository);
   const repository = git(requestedRepository, ["rev-parse", "--show-toplevel"]).trim();
   const gitDirectory = git(repository, ["rev-parse", "--absolute-git-dir"]).trim();
-  const branch = git(repository, ["branch", "--show-current"]).trim();
-  if (branch === "") fail("detached HEAD is not deployable");
-  if (options.branch !== null && branch !== options.branch) {
-    fail(`current branch ${branch} does not match required branch ${options.branch}`);
+  const configuredBranch = configuredDeployBranch(repository);
+  if (options.branch !== null && options.branch !== configuredBranch) {
+    fail(
+      `caller branch ${options.branch} conflicts with configured deploy.branch ${configuredBranch}`,
+    );
   }
+  if (options.resolveBranch) {
+    process.stdout.write(
+      `${JSON.stringify({ configured_branch: configuredBranch, push_refspec: `HEAD:refs/heads/${configuredBranch}` })}\n`,
+    );
+    process.exit(0);
+  }
+  const checkedOutBranch = git(repository, ["branch", "--show-current"]).trim();
+  if (checkedOutBranch === "") fail("detached HEAD is not deployable");
+  if (checkedOutBranch !== configuredBranch)
+    fail(
+      `checked out branch ${checkedOutBranch} does not match configured deploy.branch ${configuredBranch}`,
+    );
 
   for (const variable of ["GIT_SSH", "GIT_SSH_COMMAND"]) {
     if (process.env[variable]?.trim()) fail(`${variable} overrides folder-scoped Git SSH config`);
@@ -66,8 +80,9 @@ try {
       {
         status: "ready",
         repository,
-        branch,
-        required_branch: options.branch,
+        configured_branch: configuredBranch,
+        checked_out_branch: checkedOutBranch,
+        caller_branch: options.branch,
         upstream: upstream || null,
         remote: {
           name: options.remote,
@@ -98,10 +113,17 @@ try {
 }
 
 function parseArguments(arguments_) {
-  const parsed = { repository: ".", remote: "origin", branch: null, timeout: 15_000 };
+  const parsed = {
+    repository: ".",
+    remote: "origin",
+    branch: null,
+    timeout: 15_000,
+    resolveBranch: false,
+  };
   for (let index = 0; index < arguments_.length; index += 1) {
     const argument = arguments_[index];
-    if (argument === "--repository")
+    if (argument === "--resolve-branch") parsed.resolveBranch = true;
+    else if (argument === "--repository")
       parsed.repository = requiredValue(arguments_, ++index, argument);
     else if (argument === "--remote") parsed.remote = requiredValue(arguments_, ++index, argument);
     else if (argument === "--branch") parsed.branch = requiredValue(arguments_, ++index, argument);
@@ -109,7 +131,7 @@ function parseArguments(arguments_) {
       parsed.timeout = Number(requiredValue(arguments_, ++index, argument));
     } else if (argument === "--help") {
       process.stdout.write(
-        "Usage: preflight.mjs [--repository PATH] [--remote NAME] [--branch NAME] [--timeout-ms 1000..60000]\n",
+        "Usage: preflight.mjs [--repository PATH] [--remote NAME] [--branch CONFIGURED_BRANCH] [--resolve-branch] [--timeout-ms 1000..60000]\n",
       );
       process.exit(0);
     } else fail(`unknown argument: ${argument}`);
@@ -117,12 +139,55 @@ function parseArguments(arguments_) {
   if (!Number.isInteger(parsed.timeout) || parsed.timeout < 1_000 || parsed.timeout > 60_000) {
     fail("--timeout-ms must be an integer from 1000 to 60000");
   }
-  if (parsed.branch !== null && !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(parsed.branch)) {
-    fail("--branch must be a plain Git branch name");
-  }
   return parsed;
 }
 
+function configuredDeployBranch(repository) {
+  const configPath = resolve(repository, ".agents/config/project.yaml");
+  if (!existsSync(configPath)) return "main";
+  let document;
+  try {
+    document = parseDocument(readFileSync(configPath, "utf8"), { strict: true, uniqueKeys: true });
+  } catch (error) {
+    fail(
+      `project.yaml could not be read: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (document.errors.length > 0) {
+    fail(`project.yaml is malformed: ${document.errors[0]?.message ?? "YAML parse error"}`);
+  }
+  const config = document.toJS();
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    fail("project.yaml must contain a mapping");
+  }
+  const deploy = config.deploy;
+  if (deploy === undefined) return "main";
+  if (deploy === null || typeof deploy !== "object" || Array.isArray(deploy)) {
+    fail("project.yaml deploy must be a mapping");
+  }
+  if (!("branch" in deploy)) return "main";
+  if (typeof deploy.branch !== "string" || deploy.branch.trim() === "") {
+    fail("project.yaml deploy.branch must be a non-empty Git branch name");
+  }
+  const branch = deploy.branch.trim();
+  if (!isValidBranch(repository, branch)) fail(`project.yaml deploy.branch is invalid: ${branch}`);
+  return branch;
+}
+
+function isValidBranch(repository, branch) {
+  if (
+    branch.startsWith("-") ||
+    branch.includes("..") ||
+    branch.includes("//") ||
+    branch.includes("@{")
+  )
+    return false;
+  return (
+    git(repository, ["check-ref-format", "--branch", branch], { allowFailure: true }).trim() ===
+    branch
+  );
+}
+
 function requiredValue(arguments_, index, option) {
   const value = arguments_[index];
   if (!value || value.startsWith("--")) fail(`${option} requires a value`);

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

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+test("standalone consumer resolves fresh project targets without node_modules", () => {
+  const root = mkdtempSync(join(tmpdir(), "zaip-deploy-target-"));
+  try {
+    assert.equal(
+      spawnSync("git", ["init", "-b", "codex/working", root], { windowsHide: true }).status,
+      0,
+    );
+    const scripts = join(root, ".agents/skills/zaip-skill-github-deploy/scripts");
+    mkdirSync(scripts, { recursive: true });
+    mkdirSync(join(root, ".agents/config"), { recursive: true });
+    for (const file of ["preflight.mjs", "yaml-parser.mjs"])
+      copyFileSync(join(import.meta.dirname, file), join(scripts, file));
+    const run = (...args) =>
+      spawnSync(process.execPath, [join(scripts, "preflight.mjs"), "--repository", root, ...args], {
+        encoding: "utf8",
+        windowsHide: true,
+        env: { ...process.env, NODE_PATH: "" },
+      });
+    const target = () => {
+      const result = run("--resolve-branch");
+      assert.equal(result.status, 0, result.stderr);
+      return JSON.parse(result.stdout);
+    };
+    const config = (text) => writeFileSync(join(root, ".agents/config/project.yaml"), text);
+    assert.equal(target().configured_branch, "main");
+    config("project: { name: example }\n");
+    assert.equal(target().configured_branch, "main");
+    config("deploy: {}\n");
+    assert.equal(target().configured_branch, "main");
+    config("deploy:\n  branch: 'release/production'\n");
+    assert.deepEqual(target(), {
+      configured_branch: "release/production",
+      push_refspec: "HEAD:refs/heads/release/production",
+    });
+    config("deploy: { branch: staging }\n");
+    assert.equal(target().configured_branch, "staging");
+    assert.match(run("--resolve-branch", "--branch", "main").stderr, /conflicts with configured/);
+    assert.match(run().stderr, /checked out branch codex\/working does not match/);
+    for (const branch of ["bad..branch", "bad.lock/child", ".hidden/child", "-option"]) {
+      config(`deploy: { branch: '${branch}' }\n`);
+      assert.match(run("--resolve-branch").stderr, /deploy.branch is invalid/);
+    }
+    config("deploy: { branch: release_ }\n");
+    assert.equal(target().configured_branch, "release_");
+    for (const source of ["deploy: [\n", "deploy: { branch: main, branch: staging }\n"]) {
+      config(source);
+      assert.match(run("--resolve-branch").stderr, /malformed/);
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});