菜单
Prepara e valida a estrutura inicial da pasta paralela da KB para carga inicial, sync de XPZ, índice derivado e artefatos de importação
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | xpz-kb-parallel-setup |
| description | Prepara e valida a estrutura inicial da pasta paralela da KB para carga inicial, sync de XPZ, índice derivado e artefatos de importação |
Define e valida a estrutura inicial da pasta paralela da KB usada ao redor de uma Knowledge Base GeneXus. Essa estrutura não substitui a pasta nativa da KB; ela concentra os XPZ exportados pela IDE, os XMLs materializados pelo fluxo oficial, o índice derivado para triagem e os artefatos locais preparados para importação posterior.
Esta skill e de invocacao obrigatória antes de qualquer ação de consulta, triagem, leitura de XML ou geração de objeto em pasta que contenha ObjetosDaKbEmXml/ ou KbIntelligence/. Nenhuma outra skill de KB (xpz-index-triage, xpz-reader, xpz-builder, xpz-sync, nexa) pode ser iniciada nessa pasta enquanto esta skill não tiver sido executada na sessao corrente.
PRE-CONDICAO OBRIGATÓRIA AO SER INVOCADA PELO GATILHO GLOBAL (não se aplica quando o usuário pede explicitamente setup, atualizacao ou auditoria — nesses casos ir direto ao WORKFLOW passo 1):
Esta pre-condicao e o caminho leve de seguranca para tarefas normais do usuário na KB. Ela deve executar apenas runtime, freshness e gate de índice enquanto o freshness retornar GATE_ONLY e o índice retornar GATE_OK; não carregar nem aplicar o corpo completo do WORKFLOW nesse caminho curto. AUDIT_REQUIRED por assinatura de contrato de setup ausente, invalida ou defasada e comportamento deliberado: após git pull da base metodologica, a pasta paralela precisa ser conferida quando a superficie de contrato de xpz-kb-parallel-setup mudou, para saber se deve incorporar wrappers, gates, metadata ou regras locais novas. Commits em outras frentes do repositório que não alterem essa superficie não devem, por si só, disparar auditoria completa.
Test-*KbPowerShellRuntime.ps1 existe em scripts/ da pasta paralela e executa-lo antes de qualquer outro wrapper:
& "<caminho-absoluto-de-Test-*KbPowerShellRuntime.ps1>"
setup_bloqueado ate o wrapper ser criado via atualizar_bootstrap_localPOWERSHELL_RUNTIME_OK: prosseguir para o passo 1BLOCK: ou falhar: registrar o erro e bloquear o uso operacional da pasta paralela ate existir pwsh com PowerShell 7.4 LTS ou superiorTest-*KbSetupFreshness.ps1 existe em scripts/ da pasta paralela
& "<caminho-absoluto-de-Test-*KbSetupFreshness.ps1>"
2a. Declarar na conversa o resultado obtido pelo script antes de prosseguir:
- se GATE_ONLY: registrar "Test-*KbSetupFreshness.ps1 retornou GATE_ONLY"
- se AUDIT_REQUIRED: <motivo>: registrar "Test-*KbSetupFreshness.ps1 retornou AUDIT_REQUIRED — "
- se script ausente (verificado no passo 1): registrar "Test-*KbSetupFreshness.ps1 ausente — auditoria completa necessária"
- se erro inesperado: registrar o erro antes de decidir o próximo passo
3. Seguir o output:
AUDIT_REQUIRED: <motivo> → prosseguir com auditoria completa (WORKFLOW passo 1)GATE_ONLY → executar Test-*KbIndexGate.ps1; se GATE_OK, liberar o fluxo normal; se BLOCK, prosseguir com auditoria completa (WORKFLOW passo 1)O agente não deve raciocinar sobre timestamps por conta própria nem substituir a execução do script por verificacao manual de datas ou de arquivos.
Quando acionada pelo gatilho global, "auditoria completa" significa: executar Test-*KbPowerShellRuntime.ps1 antes dos demais wrappers; se ele estiver ausente ou retornar BLOCK:, classificar como setup_bloqueado e não executar uso operacional da pasta paralela. Com runtime aprovado, executar Test-*KbSetupAudit.ps1 (se existir), seguido de Test-*KbIndexGate.ps1 (se existir), verificar que estado_operacional_sugerido e compativel com a tarefa em curso e liberar o fluxo somente após GATE_OK. Depois da auditoria completa, o agente deve classificar explicitamente o subestado transitorio da PRE-CONDICAO antes de voltar a tarefa original; esses rotulos setup_* não são estados canonicos de conclusao e não devem ser usados como estado final do setup:
setup_apto: auditoria passou, gate passou e não ha pendencia persistente identificada no motivo original do AUDIT_REQUIRED.setup_apto_com_metadata_pendente: auditoria passou e gate passou, mas o motivo original do AUDIT_REQUIRED foi ausencia, defasagem ou inconsistencia de campo persistente em kb-source-metadata.md, como last_setup_audit_run_at ou setup_contract_signature_*.setup_bloqueado: runtime PowerShell mínimo falhou/ausente, auditoria ou gate falhou, ou estado_operacional_sugerido não e compativel com a tarefa em curso.Quando o motivo original do AUDIT_REQUIRED for assinatura de contrato de setup ausente ou defasada e a auditoria completa seguida do gate passar sem pendencia corrigivel, tratar a gravacao de last_setup_audit_run_at e setup_contract_signature_* como fechamento da pre-condicao bem-sucedida: incluir Set-*KbSetupAuditTimestamp.ps1 no plano consolidado, ou registrar recusa/adiamento explicito do usuário. Sem esse fechamento, a próxima sessao repetira a auditoria completa pelo mesmo motivo, mesmo com a pasta já conferida.
Se o subestado for setup_apto_com_metadata_pendente, o agente não pode prosseguir silenciosamente apenas porque o gate retornou GATE_OK. Antes de continuar a tarefa original, montar o plano consolidado de correcoes (seção PLANO DE CORRECOES POS-AUDITORIA), incluindo obrigatoriamente a linha de last_setup_audit_run_at e setup_contract_signature_* com Set-*KbSetupAuditTimestamp.ps1 quando a auditoria bem-sucedida permitir gravacao. Declarar que a tarefa atual está liberada pelo gate, mas a pasta repetira auditoria completa nas próximas sessoes enquanto o plano não for executado ou adiado explicitamente pelo usuário.
Quando estado_operacional_sugerido for atualizacao_metodologica_pendente: ler todas as linhas wrappers/inventario: da saida e incorporar cada pendencia (INVENTORY_GAPS, INVENTORY_SHORT_NAMING, INVENTORY_CUSTOMIZED, INVENTORY_LEGACY_ORPHANS, INVENTORY_RECOMMENDED_MISSING) ao plano consolidado de correcoes, com explicacao em portugues e sem termos tecnicos em ingles. Se houver tambem a linha consultiva INVENTORY_SURFACE_ADVISORY (que por si só NÃO leva a atualizacao_metodologica_pendente), incorpora-la ao mesmo plano como recomendacao de realinhamento de superficie, sem trata-la como bloqueio. Não acionar o WORKFLOW de criacao/documentacao (passos 1-7b) — esse WORKFLOW e reservado para quando o usuário pede explicitamente setup, atualizacao ou auditoria.
Quando a saida de Test-*KbSetupAudit.ps1 trouxer metadata wrapper: diferente de OK (PENDENTE_DE_DADOS, PENDENTE ou BLOCK), esse resultado também exige estado_operacional_sugerido=atualizacao_metodologica_pendente. GATE_OK, NAMING_OK e inventario sem gaps não neutralizam metadado de identidade ausente ou wrapper de metadata quebrado. O agente deve evidenciar a linha metadata wrapper.evidencia, distinguir campo ausente de falha funcional do wrapper e, quando a pendencia for identidade estavel ausente, oferecer reconciliacao via resolvedor/atualizador de identidade antes de declarar estado limpo.
Quando a saida trouxer metadata/deploy: diferente de OK (PENDENTE ou BLOCK), tratar como pendencia metodologica da mesma severidade: metadata wrapper: OK não prova plausibilidade semantica de kb_environment_names nem do mapeamento kb_environment_output_dirs/kb_environment_web_dirs. Para deployment_hosting_kind=java-tomcat, metadata/deploy: PENDENTE tambem pode significar ausencia dos campos dedicados kb_environment_servlet_dirs/kb_environment_app_package/kb_environment_servlet_flavor; nesse caso, usar o assistente read-only Resolve-XpzJavaTomcatMetadataSuggestion.ps1 apenas para produzir candidatos e evidencia, confrontar model.ini com gradle.properties/sentinelas/pacote e gravar por Set-*KbSourceMetadataDeployment.ps1 somente apos confirmacao explicita do usuário. O agente deve evidenciar metadata/deploy.evidencia, distinguir campos de deploy/output ausentes (PENDENTE) de metadata legado ou inconsistente (BLOCK), perguntar ao usuário os nomes exatos dos environments e os diretórios de output por environment, validar cada nome via MSBuild (SetActiveEnvironment headless) e rerodar Set-*KbSourceMetadataDeployment.ps1 com -KbEnvironmentNames, -KbEnvironmentOutputDirs e, quando aplicavel, campos Java/Tomcat opt-in antes de declarar estado limpo.
Após o setup ser concluido com sucesso, qualquer consulta de existência, localização ou triagem de XML deve ser roteada para xpz-index-triage antes de abrir arquivos individuais, quando a pasta adotar KbIntelligence.
Usar esta skill quando o trabalho exigir preparar, explicar, validar, atualizar ou corrigir a estrutura da pasta paralela da KB. O agente deve separar claramente a pasta nativa da KB da pasta paralela e aplicar os nomes padrão quando o usuário não informar alternativas.
Quando o usuário usar qualquer linguagem que sugira setup — "refazer", "reiniciar", "recriar", "atualizar", "preciso dos novos scripts", "meu gate ta falhando" ou equivalente — em pasta que já tem histórico real, assumir modo_atualizacao e confirmar brevemente com o usuário o que sera feito antes de gravar. Se o pedido for genérico, como "refazer o setup", "revisar o setup" ou equivalente, assumir por padrão a intencao auditar_setup ate que o usuário peca explicitamente corrigir_wrapper_local ou atualizar_bootstrap_local. Em pasta com histórico real, modo_criacao nunca e uma opção oferecida ou aceita; se o usuário insistir em apagar tudo ou recriar do zero, recusar, explicar que dados existentes não serao destruidos e redirecionar para modo_atualizacao.
Essa confirmacao breve antes de gravar deve ser textual, objetiva e aderente ao diagnostico em andamento. Não abrir menu, enquete, questionario ou lista de opções logo no inicio de modo_atualizacao quando a auditoria mínima obrigatória ainda não tiver sido concluida.
Em modo_atualizacao, a verificacao de naming de ObjetosDaKbEmXml não e opcional e não pode ser pulada mesmo quando todos os scripts forem EQUIVALENTE: para cada diretório presente na pasta, o agente deve ler pelo menos um XML, extrair o tipo canonico pelo GUID (ou pelo elemento raiz <Attribute>), comparar com o nome do diretório e reportar o resultado — conforme ou divergente — antes de declarar qualquer estado de conclusao.
Dentro de modo_atualizacao, separar primeiro a intencao operacional antes de avancar:
auditar_setup: o usuário quer conferir se a pasta paralela está aderente, atualizada e coerente; a saida principal e diagnostico com estado operacional, classificação de scripts, pendencias e plano consolidado de correcoes oferecido para execução na mesma sessaocorrigir_wrapper_local: o usuário quer corrigir um wrapper local defasado, quebrado ou reprovado por gate; a saida principal e edicao do wrapper, rerun do gate relevante e handoff atualizadoatualizar_bootstrap_local: o usuário quer incorporar wrappers ou seções documentais ausentes previstos pela base metodologica; a saida principal e completar o bootstrap local faltante sem recriar a pastamodo_atualizacao descreve o contexto da pasta; auditar_setup, corrigir_wrapper_local e atualizar_bootstrap_local descrevem a natureza do trabalho. Não tratar essas tres intencoes como se fossem a mesma coisa só porque acontecem na mesma pasta com histórico real.
Em auditar_setup, concluir primeiro a auditoria mínima obrigatória e, em seguida, montar e oferecer o plano consolidado de correcoes (seção PLANO DE CORRECOES POS-AUDITORIA) antes de qualquer outro próximo passo operacional. Antes disso, não oferecer sincronizar XPZ novamente, rebuild do indice ou equivalentes como resposta-padrao a um pedido de "refazer setup".
Quando auditar_setup detectar INVENTORY_SHORT_NAMING no campo wrappers/inventario da saida de Test-*KbSetupAudit.ps1: os scripts listados existem com naming curto (ex: Test-KbIndexGate.ps1) em vez do naming canonico com prefixo KB (ex: Test-wsEducacaoSpTesteKbIndexGate.ps1). Essa divergencia NÃO e opcional, NÃO pode ser descartada como "convencao consistente aceita", NÃO e neutralizada por GATE_OK, STRUCTURE_OK ou pelo fato de os scripts funcionarem operacionalmente. O naming curto e uma divergencia do padrão desta skill. O agente deve: classificar cada script SHORT_NAMING como CUSTOMIZADO com ação de renome na tabela de 8.h; oferecer atualizar_bootstrap_local para executar os renomes; incluir os renomes na lista de trabalho da sessao corrente — não adiar para sessao futura nem condicionar a confirmacao a que o usuário mencione o problema primeiro.
Quando auditar_setup detectar INVENTORY_CUSTOMIZED no campo wrappers/inventario da saida de Test-*KbSetupAudit.ps1: os scripts listados existem, mas divergem metodologicamente do exemplo canonico correspondente. Divergencia de #requires -Version e divergencia metodologica objetiva quando o exemplo canonico declara uma versão e o wrapper local declara outra versão, mesmo que a lógica funcional restante seja equivalente. A ausencia de repasse de -AsJson nos wrappers K8/K9 Test-*KbSetupAudit.ps1/Test-*KbIndexGate.ps1 (motivo missing_AsJson_passthrough) e outra divergencia metodologica objetiva. O repasse, a um motor compartilhado advanced, de um parametro que o motor nao declara (motivo forwards_unknown_engine_param), um caminho de motor inferido inexistente na base canonica (motivo shared_engine_unresolved), a saida insegura exit $LASTEXITCODE em wrapper auditado que chama motor PowerShell por variavel (motivo unsafe_last_exitcode_after_ps1_engine) e a PERDA de contrato obrigatorio da superficie do molde (motivo surface_mismatch — obrigatorio do molde ausente/rebaixado ou param() de topo ausente com molde obrigatorio, pelo diff de superficie param()/ValidateSet), são igualmente divergencias metodologicas objetivas detectadas mecanicamente pelo inventario. O agente deve classificar cada script listado como CUSTOMIZADO na tabela de 8.h, evidenciar o motivo emitido pelo inventario e não declarar wrappers_atualizados nem materializado_e_indice_validado como estado limpo ate haver decisão explicita sobre a correcao.
Quando auditar_setup detectar INVENTORY_LEGACY_ORPHANS no campo wrappers/inventario da saida de Test-*KbSetupAudit.ps1: os scripts listados são nomes antigos que permaneceram na pasta scripts/ depois que o nome canonico atual já existe. Isso e pendencia metodologica objetiva porque mantem allowlists e documentação local apontando para comandos antigos. O agente deve classificar o arquivo legado como CUSTOMIZADO/legado na tabela de 8.h, oferecer remocao segura e atualizacao de referencias em .claude\settings.json, AGENTS.md, README.md e scripts locais, sempre com aprovacao explicita antes de apagar ou editar.
Quando auditar_setup detectar metadata wrapper: PENDENTE_DE_DADOS, metadata wrapper: PENDENTE ou metadata wrapper: BLOCK, ou metadata/deploy: PENDENTE ou metadata/deploy: BLOCK, não declarar materializado_e_indice_validado nem gravar last_setup_audit_run_at e setup_contract_signature_* como conclusao bem-sucedida. Se o próprio estado_operacional_sugerido ainda vier limpo nesse cenário, tratar como divergencia do motor de auditoria e corrigir a metodologia antes de usar o resultado para liberar a pasta.
Aplica-se sempre que esta skill tiver concluido auditoria mínima — seja em auditar_setup, no BLOCO DE ATUALIZACAO de modo_atualizacao ou na auditoria completa da PRE-CONDICAO do gatilho global (após Test-*KbSetupAudit.ps1 e Test-*KbIndexGate.ps1 com GATE_OK, quando aplicavel). Não substitui as regras de aprovacao explicita antes de gravar; consolida o que oferecer corrigir e em que ordem, para o usuário não precisar descobrir pendencia por pendencia.
Ao terminar a auditoria, o agente deve entregar ao usuário:
Test-*KbSetupAudit.ps1 quando existir, tabela 8.h quando modo_atualizacao).atualizar_bootstrap_local, corrigir_wrapper_local, passo 34, etc.).GATE_OK pode liberar a tarefa original do usuário em paralelo ao plano, mas não dispensa apresentar o plano quando houver item corrigivel.
Consolidar todos os itens abaixo que a auditoria tiver identificado; omitir um item da lista e proibido quando a evidencia existir:
| Origem tipica | Item no plano | Ação preferida | Aprovacao antes de gravar |
|---|---|---|---|
setup_apto, setup_apto_com_metadata_pendente ou passo 34 após AUDIT_REQUIRED | last_setup_audit_run_at ou setup_contract_signature_* ausente, vazio ou defasado após auditoria OK; inclui contrato de setup atualizado | Set-*KbSetupAuditTimestamp.ps1; rerodar freshness e index gate | Sim, se regra local exigir |
INVENTORY_GAPS / scripts AUSENTE em 8.h | Wrappers ou gates ausentes previstos | atualizar_bootstrap_local a partir dos .example.ps1 | Sim |
INVENTORY_SHORT_NAMING | Naming curto de wrapper | Renome canonico em lote (8.c exceção 2) | Sim, confirmacao em lote |
INVENTORY_LEGACY_ORPHANS | Script legado lado a lado com canonico | Remocao segura + atualizar referencias (8.f.1) | Sim |
INVENTORY_CUSTOMIZED (não SHORT_NAMING) | Wrapper divergente do exemplo | Menu 8.c ou caso deterministico → corrigir_wrapper_local | Sim, por script ou lote |
INVENTORY_SURFACE_ADVISORY (consultivo, não bloqueia) | Wrapper local defasado do molde por reducao opcional/ValidateSet (diff de superficie param()) | Realinhar a superficie ao molde preservando defaults locais; nunca recopiar integral | Sim, se o usuário optar por realinhar |
| Caso deterministico (8.a.iii, 8.z) | Wrapper defasado com correcao inequivoca | corrigir_wrapper_local sem menu A/B/C/D | Sim, se regra local exigir |
metadata wrapper ≠ OK | Identidade ou contrato de metadata | Reconciliacao via Resolve-*KbIdentity / Update-*KbMetadataIdentity ou corrigir wrapper | Sim |
metadata/deploy ≠ OK | Plausibilidade de environment/deploy/output em kb-source-metadata.md; em java-tomcat, também metadata de WEB-INF\classes/pacote/flavor | Perguntar nomes e diretórios de output ao usuário, usar Resolve-XpzJavaTomcatMetadataSuggestion.ps1 como assistente read-only quando aplicavel, rerodar Set-*KbSourceMetadataDeployment.ps1 com -KbEnvironmentNames + -KbEnvironmentOutputDirs + campos Java opt-in + validação MSBuild; corrigir wrapper se uses_removed_inventory_discovery ou parâmetro obrigatório de environment/output ausente; tratar ausência de parâmetro Java/Tomcat opt-in indicada por INVENTORY_SURFACE_ADVISORY como realinhamento consultivo de superfície | Sim |
declarativo/timestamps=DRIFT_TIMESTAMPS_LITERAIS | Timestamps literais em AGENTS.md/README.md | Substituir por ponteiros (examples/AGENTS.md.example) | Sim |
Seção ## Triagem Por Indice ausente (8.g) | Roteamento para xpz-index-triage | Inserir bloco padrão no AGENTS.md local | Sim |
INVENTORY_RECOMMENDED_MISSING | Wrappers finos recomendados | Criar a partir dos .example.ps1 | Sim |
Naming divergente em ObjetosDaKbEmXml (8.g2) | Diretórios com tipo real ≠ nome da pasta | Renome seguro com aprovacao | Sim |
| Prefixo verbal defasado (8.f) | Nome local ≠ exemplo canonico (Update- vs Rebuild-, etc.) | Renome + atualizar referencias | Sim |
Test-*KbPowerShellRuntime.ps1 ausente | Runtime gate ausente | Incorporar wrapper de runtime | Sim |
Não prometer no plano consolidado o que pertence a outra frente, salvo mencionar como fora de escopo com skill responsável:
last_xpz_materialization_run_at → xpz-syncxpz-sync encadeadoQuando o usuário aprovar o pacote, executar na ordem abaixo salvo bloqueio concreto:
Test-*KbPowerShellRuntime.ps1 presente e OK (se estava ausente).corrigir_wrapper_local) que desbloqueiam gates.atualizar_bootstrap_local para scripts AUSENTE e renomes SHORT_NAMING.AGENTS.md/README.md) e seção de triagem por índice.Set-*KbSetupAuditTimestamp.ps1) quando auditoria bem-sucedida permitir.metadata wrapper exigir.Set-*KbSourceMetadataDeployment.ps1 com -KbEnvironmentNames e -KbEnvironmentOutputDirs confirmados pelo usuário + validação MSBuild obrigatória; em java-tomcat, campos Java opt-in sugeridos por Resolve-XpzJavaTomcatMetadataSuggestion.ps1 e confirmados pelo usuário) e correcao do wrapper local quando metadata/deploy, uses_removed_inventory_discovery ou parâmetro obrigatório de environment/output ausente exigirem. Se INVENTORY_SURFACE_ADVISORY indicar ausência de parâmetro Java/Tomcat opt-in no wrapper, oferecer realinhamento consultivo de superfície ao molde, preservando defaults locais; não tratar isso como bloqueio por INVENTORY_CUSTOMIZED. Imediatamente após gravar campos de deploy, reexecutar Test-*KbMetadataWrapper.ps1: a gravacao torna obrigatório que Get-*KbMetadata.ps1 exponha os campos novos, então um leitor antes aprovado pode passar a bloquear com BLOCK: <campo> existente no metadata nao foi exposto pelo wrapper. Quando isso ocorrer, e o caso deterministico de 8.a.iii — alinhar Get-*KbMetadata.ps1 ao exemplo canonico antes de seguir, sem abrir menu A/B/C/D.INVENTORY_RECOMMENDED_MISSING e naming de ObjetosDaKbEmXml aprovados pelo usuário.Test-*KbSetupAudit.ps1, Test-*KbSetupFreshness.ps1 (se existir) e Test-*KbIndexGate.ps1; atualizar handoff.Depois de classificar o subestado transitorio (setup_apto, setup_apto_com_metadata_pendente, setup_bloqueado):
setup_bloqueado: não voltar a tarefa original; plano só com o que for corrigivel para destravar.setup_apto ou setup_apto_com_metadata_pendente com itens corrigiveis: montar o plano consolidado antes de retomar a tarefa original; itens de metadata pendente entram como linhas do plano, não como único aviso solto. Quando o único item for atualizar last_setup_audit_run_at e setup_contract_signature_* após auditoria bem-sucedida exigida por assinatura de contrato ausente ou defasada, ele ainda deve aparecer no plano para restaurar o caminho GATE_ONLY das próximas sessoes.auditar_setupauditar_setup não fecha apenas com diagnostico. Fecha com diagnostico + plano consolidado oferecido + registro da decisão do usuário (executar agora, recusar, adiar ou executar subconjunto). Se o usuário aprovar execução, o agente pode transitar para atualizar_bootstrap_local e/ou corrigir_wrapper_local na mesma sessao sem exigir novo pedido do usuário.
A skill xpz-llm-delegate usa um arquivo de politica por-KB na raiz da pasta paralela para autorizar de forma duravel o envio de conteúdo desta KB a modelos externos (ver xpz-llm-delegate/SKILL.md). O nome canonico e llm-delegation-policy.json; o nome legado opencode-delegation-policy.json permanece aceito para retrocompatibilidade.
ask no gate (Resolve-LlmDelegateAuthorization.ps1); adiar nunca abre brecha.llm-delegation-policy.json (nome canonico) com schemaVersion, defaultExternal e entradas finas por provider/modelo conforme a escolha; nunca presumir allow-external por conta própria.opencode-delegation-policy.json, ele continua valendo; oferecer (sem cobrar) renomear para llm-delegation-policy.json. Com os dois presentes, o scripts/Resolve-LlmDelegationPolicyPath.ps1 usa o canonico e sinaliza status=both.scripts/Build-LlmDelegateCapabilityManifest.ps1 -SnapshotPath <raiz-paralela>\Temp\llm-delegate-capabilities.snapshot.json, para alimentar a oferta de revisao por pares (ver 15-revisao-por-pares.md) sem re-sondar a cada uso. Capacidade != autorizacao: arquivo separado da politica, fica em Temp/ (ja ignorado pelo git), e cache re-derivavel e dica de oferta, nunca verdade do gate — o Resolve-LlmDelegateAuthorization.ps1 reavalia destino e sensibilidade sempre. Na revisao, comparar snapshotAt/sourceGeneratedAt e perguntar ao usuario se quer atualizar a sondagem ou seguir com o anotado; sem re-sondagem automatica.SKILL.md fica dentro de uma subpasta de skill sob a raiz do repositório.../arquivo.md deve ser resolvida a partir da pasta deste SKILL.md, e não do diretório de trabalho corrente.../ aponta para a base metodológica compartilhada na pasta-pai desta skill.examples/, resolver primeiro a pasta irmã do SKILL.md publicado na sessão. Se o SKILL.md publicado vier de fora do repositório corrente, não procurar examples/ primeiro dentro do workspace atual só porque existe uma pasta de nome parecido.examples/ publicados ainda não tiver ocorrido, a auditoria pode seguir provisoriamente com evidência local já disponível (GATE_OK, STRUCTURE_OK, parse dos wrappers, presença de seções obrigatórias e verificação de naming), deixando a classificação final contra os exemplos como etapa pendente explícita em vez de abrir exploração ampla de caminhos cedo demais.Use esta skill para:
XPZsync, geração de XML ou empacotamentoKbIntelligenceTest-*KbMetadataWrapper.ps1, Test-*KbIndexGate.ps1 ou Test-*KbStructure.ps1pwsh com PowerShell 7.4 LTS ou superior não estiver disponívelAGENTS.md da pasta paralela está desatualizado em relacao ao padrão canonico atual — por exemplo, ausencia de seção ## Triagem Por Indice, lista de wrappers incompleta ou outras seções ausentes identificadas por comparacao com examples/AGENTS.md.exampleObjetosDaKbEmXml corresponde ao GUID real de cada objeto — especialmente Folder/, Module/ e PackagedModule/ — e propor correcao quando houver inversao ou divergenciaPacotesGeradosParaImportacaoNaKbNoGenexus/ populado, wrapper local de import, ou tarefa mencionando importar, preview, MSBuild import, import_file.xml ou pacote gerado); ver seção ## CAPACIDADE DE IMPORTACAO HEADLESSDo NOT use this skill for:
XPZ específico no acervo oficial (use xpz-sync)xpz-builder)xpz-reader)xpz-index-triage)pasta paralela da KBscriptsTempXpzExportadosPelaIDEObjetosDaKbEmXmlKbIntelligenceObjetosGeradosParaImportacaoNaKbNoGenexusPacotesGeradosParaImportacaoNaKbNoGenexusAGENTS.md e, quando fizer sentido para humanos, também em README.md dentro da própria pasta paralela da KBAGENTS.md da pasta paralela o caminho confirmado da pasta nativa da KBAGENTS.md da pasta paralela que a pasta nativa da KB e terreno proibido para gravacao por agentes, com leitura permitida apenas quando o fluxo operacional explicito realmente exigirREADME.md local para humanos na pasta paralela, espelhar ali a identificacao da pasta nativa da KB e a regra de somente leitura em linguagem claraObjetosDaKbEmXml como snapshot oficial somente leitura para agentesObjetosDaKbEmXml é o snapshot oficial da KB e agentes não o editam manualmente (editar o acervo esperando que o pacote use essa versão é anti-padrão; ver 02-regras-operacionais-e-runtime.md, anti-padrão "editar acervo esperando que o pacote pegue")ObjetosGeradosParaImportacaoNaKbNoGenexus é a área intermediária de trabalho anterior ao retorno oficial da KB e não atualiza diretamente o acervo oficialObjetosDaKbEmXmlObjetosDaKbEmXml só é atualizado depois que a KB devolve XPZ oficial e o xpz-sync materializa esse retornoXpzExportadosPelaIDE como pasta de entrada onde o usuário grava os .xpz exportados pela IDETemp como destino preferencial para artefatos efemeros, temporarios de execução, relatórios descartaveis e copias temporarias de SQLiteKbIntelligence como pasta do índice SQLite derivado e regeneravel, normalmente KbIntelligence\kb-intelligence.sqlite, mais relatórios de validação quando o repositório local adotar esse fluxokb-source-metadata.md como metadado operacional da materialização XPZ/XML; ele deve expor last_xpz_materialization_run_at quando o fluxo oficial tiver processado um insumo da IDEainda nao materializada, aguardando primeiro XPZ ou equivalente como estado provisório; depois da primeira materialização oficial bem-sucedida, esse estado não deve continuar sendo apresentado como atualKbIntelligence\kb-intelligence.sqlite como dono do metadado last_index_build_run_at na tabela metadata; esse horario deve ser igual ou posterior a last_xpz_materialization_run_at para permitir triagem ampla e geração de objetos de importação; last_index_build_run_at e a fonte autoritativa do estado de frescor do índice — qualquer decisão sobre frescor do índice deve consultar esse campo via query index-metadata, não criar campo derivado ou espelho em kb-source-metadata.mdTest-*KbIndexGate.ps1 deve validar extractor_signature_version e extractor_signature_hash na metadata do SQLite contra o motor compartilhado (scripts/GeneXusKbIntelligenceExtractorContract.ps1 + scripts/Build-KbIntelligenceIndex.py no repositório ativo). Índice sem assinatura ou com assinatura divergente bloqueia com BLOCK: mesmo quando last_index_build_run_at >= last_xpz_materialization_run_at — regenerar o índicexpz-kb-parallel-pre-push: o estado_operacional_sugerido do Test-*KbSetupAudit.ps1 e o status/reason do Test-*KbIndexGate.ps1 (sob -AsJson) são consumidos pelos gates K8/K9 do orquestrador Invoke-XpzKbParallelPrePushPhase1.ps1 daquela skill. Renomear esses literais aqui é breaking para a rotina pré-push de pasta paralela — alterar os dois lados juntos. scripts/Test-XpzKbIndexGate.ps1 faz parte do setup-contract.manifest.json justamente por ser consumido por essa viaRebuild-*KbIntelligenceIndex.ps1 (motor scripts/Build-KbIntelligenceIndex.ps1) exige Python 3.x utilizavel no PATH (scripts/GeneXusPythonPrerequisite.ps1; stub da Microsoft Store em WindowsApps não conta). Ausencia bloqueia o refresh com exit 8 e mensagem PREREQUISITO AUSENTE — rigor: sync normal não terminou; a materialização XPZ/XML em ObjetosDaKbEmXml pode já ter concluido, mas isso não equivale a sucesso do fluxo oficial nem autoriza triagem ampla sem índice. Não tratar como falha do pacote exportado; instalar Python 3.x e rerodar o rebuild (Rebuild-*KbIntelligenceIndex.ps1). O molde Update-KbFromXpz.example.ps1 propaga essa mensagem quando o encadeamento de rebuild falhar no mesmo pwsh. Ver README.md, 02-regras-operacionais-e-runtime.md e xpz-sync da base compartilhadakb-source-metadata.md e a saida de -Query index-metadata do wrapper local como fontes autoritativas dos timestamps operacionais de materialização e índice; AGENTS.md e README.md locais servem como memoria auxiliar humana (wrappers, fluxos, pacotes de referencia) e não devem gravar timestamps literais de last_xpz_materialization_run_at ou last_index_build_run_at — apenas ponteiros para as fontes autoritativas e para a linha declarativo/timestamps em Test-*KbSetupAudit.ps1kb-source-metadata.md por autoridade de campo, não por dono único do arquivo:
Source/kb (GUID), Source/username, Source/UNCPath, Source/Version/guid, Source/Version/name): autoridade primaria do setup/resolvedor da KB nativa local; autoridade secundaria do XPZ somente quando o pacote vier completo e coerente com a KB localKMW (MajorVersion, MinorVersion, Build): autoridade primaria do XPZ real ou template real comparavel; setup não deve inventar esses valores sem evidencialast_xpz_materialization_run_at, source_xpz, source_refresh_status): autoridade do fluxo xpz-synclast_setup_audit_run_at, setup_contract_signature_version, setup_contract_signature_hash): autoridade desta skill, nos estados canonicos permitidosdeployment_environment_name, deployment_hosting_kind, kb_environment_count, kb_environment_names, kb_environment_output_dirs, kb_environment_web_dirs): autoridade declarada pelo usuário (nomes exatos como na IDE e diretórios de output confirmados por environment) via scripts/Set-XpzKbSourceMetadataDeployment.ps1 (wrapper local Set-*KbSourceMetadataDeployment.ps1); obrigatório -KbEnvironmentNames, -KbEnvironmentOutputDirs e validação MSBuild (SetActiveEnvironment headless sobre a lista informada); kb_environment_web_dirs pode ser derivado de -KbNativePath + output dir + web, sem scan; scan/inventario automático por pastas da KB nativa (-InventoryFromKbNativePath, -InventoryFromGeneXusMsBuild) removido; -SkipEnvironmentNamesMsBuildValidation só quando sondagem MSBuild indisponivel por infraestrutura; build/import/diagnostico de .cs só leem metadata gravadodeployment_environment_name como identificador MSBuild aceito por SetActiveEnvironment (ex.: NETPostgreSQL), não nome descritivo de GetEnvironmentProperty -Name Namedeployment_hosting_kind como um dos valores do registro-fonte-única GeneXusKbHostingKindSupport.ps1 (dotnet-core-self-host, dotnet-framework-iis, java-tomcat), validado em runtime contra o registro (não mais por [ValidateSet]; a escrita em Set-XpzKbSourceMetadataDeployment.ps1 e o diagnóstico de consistência rejeitam valor fora do registro com mensagem canônica). A partir da Fase 3, o suporte é PER-EIXO (deployBinSupportState/sourceSupportState/runtimeSupportState); cada consumidor discrimina pelo predicado do seu eixo (runsDeployBinEngine/runsSourceEngine/runsRuntimeEngine), não pelo alias legado runsFreshnessEngine. Para os hosting kinds .NET, o gate pos-import olha publicacao em web\bin (DLL de objeto + config), não GxNetCoreStartup.dll sozinha (xpz-msbuild-build, exit 49). java-tomcat tem Eixo A (deploy-bin) com motor (co-gate por conjunto de artefatos, alvo externo WEB-INF\classes) — fresh/stale/no-evidence/unexpected-publication/unknown; os Eixos B/C (.cs/.java e runtime) seguem sem motor (recognized-no-engine, Pós-v1) e pulam (skipped-hosting-unsupported/exit 0) — skip ≠ deploy validadokb_environment_servlet_dirs (= alvo externo que termina em WEB-INF\classes), kb_environment_app_package (pacote da app, ex.: com\<kb>) e kb_environment_servlet_flavor (jakarta|javax). São AUDIT_REQUIRED (autoria declarada pelo usuário; model.ini/GeneratorType nunca autoridade). A Fase 5 Java/Tomcat (EBTECH, 2026-07-07) mediu Jakarta e também um environment GeneXus JAVA_EE/Gradle javaEE com sinais reais javax em Tomcat 11/JDK 21/Servlet 6; Java EE clássico puro Tomcat 8/9 + JDK 8 segue não medido. A mesma Fase 5 mostrou que SERVLET_DIR do model.ini é evidência útil só após resolver o environment/bloco correto; quando houver Gradle, confrontar também <output>\web\gradle.properties (TOMCAT_WEBAPP_PATH, TOMCAT_STATIC_PATH) e aceitar o alvo apenas depois de auditar WEB-INF\classes, a sentinela irmã WEB-INF\lib\GeneXus.jar e a compatibilidade do pacote da app declarado. Divergência entre model.ini e gradle.properties deve virar auditoria/decisão humana, não escrita cega. Resolve-XpzJavaTomcatMetadataSuggestion.ps1 é assistente read-only para produzir candidatos e evidência; a gravação continua opt-in via Set-XpzKbSourceMetadataDeployment.ps1/wrapper local, com -KbEnvironmentServletDirs e -KbEnvironmentAppPackage obrigatoriamente completos para todos os environments declarados quando usados. Test-XpzKbMetadataWrapper.ps1 audita a exposição desses campos pelo wrapper e Test-XpzKbDeploymentMetadata.ps1 valida plausibilidade/forma. Sem esses campos, o co-gate Java resolve config-error → unknown (fail-safe), nunca fresh; com eles, o motor usa kb_environment_app_package como allowlist e a falta de artefatos sob o pacote aparece pela classificação do co-gate, não por validação de metadata. Auto-população sem confirmação continua fora de escopo.kb_environment_post_build_event_hashes (fingerprints SHA-256 dos eventos pos-build conhecidos por environment, encoding plano env=h1,h2; env2=h3) como autoridade desta skill via scripts/Register-GeneXusKbPostBuildEvents.ps1: registra a partir do JSON de um build (stdoutSignals.postBuildEvents), filtra saídas inertes estritamente reconhecidas (REM comentado, duração TimeSpan válida ou data civil válida), grava o campo plano e a secao-espelho legivel ## Eventos pos-build registrados (linhas cruas, só para auditoria humana — o build le os hashes, não o espelho). O fingerprint normaliza apenas variações inocuas previstas pelo motor, como tempo: <n> ms na saída Verify-GxJs com invalidos: 0; os demais campos continuam fazendo parte do hash. Ação sensivel — registrar desarma o rebaixamento por evento pos-build daquele environment: exige confirmacao (frase exata interativa ou -ConfirmRegistration em modo agente, após o usuário aprovar). O build (xpz-msbuild-build) compara os eventos observados por fingerprint: registrado = esperado (não rebaixa); não registrado = rebaixa por cautela; sem registro, rede de seguranca reconhece player de som como benignokb_environment_count = 1 como permissao para omitir -EnvironmentName nos wrappers de build quando o environment ativo GeneXus for o único da KB; kb_environment_count > 1 exige -EnvironmentName explicito ou deployment_environment_name preenchido antes de validação pós-import (xpz-msbuild-build)modo_atualizacao ou quando campos de environment/deploy/output estiverem ausentes ou suspeitos: perguntar ao usuário (1) quais são os environments GeneXus desta KB — nomes exatos como na IDE / SetActiveEnvironment; (2) qual e o environment de deploy/validacao headless; (3) qual diretório de output corresponde a cada environment (ex.: NETPostgreSQL=NETPostgreSQL, .Net Environment=NETFrameworkPostgreSQL); executar Set-XpzKbSourceMetadataDeployment.ps1 (ou wrapper local) com -DeploymentEnvironmentName, -DeploymentHostingKind, -KbEnvironmentNames, -KbEnvironmentOutputDirs, -KbNativePath e -InventoryWorkingDirectory; validação MSBuild e obrigatória salvo sondagem indisponivel (-SkipEnvironmentNamesMsBuildValidation com pendencia explicita no handoff). kb_environment_web_dirs pode ser derivado pelo motor quando -KbNativePath estiver presente; scan automático de pastas da KB nativa e proibido.Source/kb (GUID) como bloqueio de seguranca: se um pacote, template ou XPZ trouxer GUID de KB preenchido e diferente da KB nativa local registrada/resolvida para a pasta paralela, o agente não deve trocar o Source para normalizar o pacote nem prosseguir com import headless; deve bloquear a automacao e encaminhar o usuário para importação manual pela IDEimport_file.xml, registrar em AGENTS.md local uma seção opcional ## Pacote de referencia conhecido listando o caminho de pelo menos um pacote real comparavel para cada natureza de pacote praticada nesta pasta (full, delta cirurgico, migracao). Esse caminho serve como candidato default para -TemplatePackagePath do motor compartilhado scripts/New-XpzImportPackage.ps1 em rodadas futuras, conforme a regra de comparabilidade documentada em xpz-builder/SKILL.md. Quando essa seção não existir ou não apontar pacote comparavel ao caso corrente, o agente que invocar o motor deve omitir -TemplatePackagePath e aceitar o envelope mínimo (warning envelope-minimo) explicitamente. Manter essa seção como opcional: a pasta paralela pode operar sem ela enquanto o usuário não tiver pacote comparavel para citarlast_setup_audit_run_at em kb-source-metadata.md como timestamp da última execução de setup ou auditoria de setup concluida com sucesso nesta pasta paralela; tratar setup_contract_signature_version e setup_contract_signature_hash como a assinatura de contrato de xpz-kb-parallel-setup validada nessa auditoria. Gravar esses campos imediatamente após declarar qualquer estado canonico de conclusao bem-sucedido (pronto_para_primeira_materializacao, materializado_e_indice_validado, wrappers_atualizados); não gravar quando a conclusao for bootstrap_incompleto, auditoria_de_empacotamento_pendente ou atualizacao_metodologica_pendente, pois esses estados indicam conclusao parcial e não garantem que a próxima invocacao pode confiar no setup como integro. Esses campos são diferentes dos timestamps operacionais de materialização e índice: last_xpz_materialization_run_at pertence ao fluxo xpz-sync; last_index_build_run_at pertence ao SQLite do KbIntelligence; last_setup_audit_run_at e setup_contract_signature_* pertencem somente a auditoria de setup bem-sucedida.ObjetosDaKbEmXml.xpz em XpzExportadosPelaIDE pode ser renomeado para processado_<nome-original>.xpzObjetosGeradosParaImportacaoNaKbNoGenexus como area de trabalho para XMLs temporarios destinados a importação manual na IDEPacotesGeradosParaImportacaoNaKbNoGenexus como area de saida para import_file.xml e, quando aplicavel, XPZObjetosGeradosParaImportacaoNaKbNoGenexus e PacotesGeradosParaImportacaoNaKbNoGenexus como areas gerenciadas por agente, não como deposito geral do usuário; XML de referencia, exemplo ou template deixado na frente ativa deve ser bloqueio de empacotamento ate ser removido ou tratado por caminho explicito fora da frenteObjetosGeradosParaImportacaoNaKbNoGenexus e PacotesGeradosParaImportacaoNaKbNoGenexus não precisam ser versionadas em Git; se houver duvida sobre rastrear ou ignorar seu conteúdo, tratar isso como decisão de politica do repositório e pedir aprovacao explicitaObjetosGeradosParaImportacaoNaKbNoGenexus use sua própria subpasta NomeCurto_GUID_YYYYMMDDNomeCurto_GUID_YYYYMMDD combina nome curto, GUID criado na abertura da frente e data de criacao da frente; YYYYMMDD representa a data de criacao da frente, não a data do pacoteNomeCurto_GUID_YYYYMMDD e a unidade ativa da frentePacotesGeradosParaImportacaoNaKbNoGenexus permaneça plano, sem subpastas por frenteXPZ completos podem ser usados a qualquer momento para reatualizar ObjetosDaKbEmXmlObjetosDaKbEmXml em pasta paralela existente, ler pelo menos um XML de cada diretório de container (Folder/, Module/, PackagedModule/) e verificar o Object/@type real antes de qualquer conclusao sobre inversao ou conformidadePacotesGeradosParaImportacaoNaKbNoGenexus, auditar separadamente a aderencia do fluxo de empacotamento local; sync/indice OK não autorizam concluir sozinho que "está tudo certo"XPZ completo da IDE inclui quebrar o full.xml em XMLs individuais por objetoguid, parentGuid, parentType e moduleGuid são metadados de apoio para consistencia e rastreabilidade, não o eixo principal de organizacaoKbIntelligence só pode ser gerado depois que ObjetosDaKbEmXml existir e contiver o snapshot oficial materializadoKbIntelligence não substitui ObjetosDaKbEmXml; ele e uma camada derivada para triagem e deve ser regeneravel a partir do snapshot oficiallast_index_build_run_at estiver ausente ou anterior a last_xpz_materialization_run_at, o agente não deve pesquisar o acervo em massa nem gerar objetos para importação; deve tratar isso como exceção operacional e oferecer a regeneracao/validacao do índice antes de seguir.ps1 na pasta scripts quando a pasta paralela da KB precisar reconstruir o fluxo operacional local sobre o motor compartilhado; distinguir: scripts com parâmetros estáticos da KB (caminhos fixos, nome da KB, GUIDs) merecem wrapper local; scripts com parâmetros totalmente dinâmicos por execução (ex: Watch-GeneXusMsBuildLog.ps1, cujo -Pid e -LogPath variam a cada build) são chamados diretamente do motor pelo caminho absoluto, sem wrapper localTest-*KbPowerShellRuntime.ps1 como primeiro gate de qualquer uso operacional da pasta paralela; ele deve delegar ao motor compartilhado scripts\Test-XpzPowerShellRuntime.ps1, exigir pwsh com PowerShell 7.4 LTS ou superior e bloquear o prosseguimento quando retornar BLOCK: ou estiver ausenteSource antes do empacotamentoscripts como parte do bootstrap técnico esperado, não como pendencia para a etapa seguintesetup inicial concluido, estrutura pronta ou equivalente final se a pasta ainda não tiver a camada mínima de wrappers locais necessária para materialização oficial e, quando adotado, para KbIntelligence.gitignore na raiz e .gitkeep nas subpastas estruturais vazias como parte esperada do setup inicial padrãogit init por conta própria no setup inicial.gitignore — independente de o repositório já estar versionado ou não — cobrir obrigatoriamente: Temp, KbIntelligence (apenas kb-intelligence.sqlite e kb-intelligence-validation.json), ObjetosGeradosParaImportacaoNaKbNoGenexus, PacotesGeradosParaImportacaoNaKbNoGenexus e XpzExportadosPelaIDE; ObjetosDaKbEmXml não deve ser ignorado pelo .gitignore pois e o acervo oficial versionavel.gitignore com o padrão pasta/* e !pasta/.gitkeep deve ter o arquivo .gitkeep correspondente criado no mesmo passo em que o .gitignore e gravado; não criar .gitignore que referencia .gitkeep sem criar o arquivo físico.gitignore, politica de versionamento ou escopo de arquivos rastreados para viabilizar git add/commit e decisão de politica do repositório; o agente pode diagnosticar e propor opções, mas não deve mudar essa politica automaticamente só para concluir o fechamentokb-source-metadata.md inicial em formato compativel com o motor compartilhado, preservando desde o setup o campo nominal last_xpz_materialization_run_atscripts\Resolve-GeneXusKbIdentity.ps1 antes de declarar o metadata apto e gravar kb-source-metadata.md já com Source/kb (GUID), Source/username, Source/UNCPath, Source/Version/guid e Source/Version/name preenchidos quando a resolucao passar. Se a resolucao falhar, não declarar estado limpo de metadata; registrar a pendencia e orientar a correcao em vez de depender de XPZ futuro com Source preenchido.AGENTS.md, README.md e arquivos operacionais locais são a camada preferencial de memoria do setupObjetosDaKbEmXml ainda não foi materializadaObjetosDaKbEmXml ainda não foi materializada, exigir refresh dessa memoria local depois da primeira materialização oficial bem-sucedida, para evitar handoff com estado desatualizadomodo_criacao, antes de iniciar qualquer escrita, verificar se o prompt de entrada já declara explicitamente a preferencia por A) ou B); se sim, prosseguir sem perguntar; se não, perguntar ao usuário qual caminho prefere antes de comecar qualquer trabalho — a pergunta deve ser feita no inicio da skill, não após o setup estar concluido; agente que cria toda a estrutura e só entao pergunta A/B obriga o usuário a aguardar o setup inteiro para responder algo que podia ser respondido antes de qualquer escritaA) o usuário exporta o .xpz full pela IDE do GeneXus para XpzExportadosPelaIDE e o agente materializa os XMLs depoisB) o agente tenta gerar o .xpz full a partir da pasta nativa da KB, grava esse .xpz em XpzExportadosPelaIDE e depois materializa os XMLsA) e B), dizer explicitamente que A) e o caminho preferencial e normalmente mais rápido, enquanto B) tende a demorar mais por depender da trilha via MSBuildA), preferir descrição funcional estavel como export full da KB pela IDE em vez de depender de rotulos exatos de menu, tela ou botao do GeneXus como se fossem universais; se citar caminho de menu, apresentá-lo depois da instrucao principal e marcado explicitamente como exemplo opcional de navegacao, nunca como passo normativo principalB), encaminhar a geração do .xpz full pela skill xpz-msbuild-import-export em vez de improvisar exportação fora dessa trilhaB), verificar em kb-source-metadata.md se o campo kb (GUID) na seção ## Source foi populado com um GUID real e coerente com a KB nativa local. Exportacoes full geradas via MSBuild ou IDE podem não conter Source completo; isso deve ser tratado como metadata incompleto a resolver pela identidade local aprovada, não como motivo automático para pedir reexport. Se o pacote trouxer GUID preenchido de outra KB, bloquear import headless e orientar importação manual pela IDEB), quando o export.json emitido por Invoke-GeneXusXpzExport.ps1 vier com postProcessingFailed=true mas o msbuild.stdout.log contiver Export Sucesso e __EXPORTED_FILE__=<caminho> e o arquivo XPZ existir no caminho indicado, NÃO classificar a rodada como falha operacional nem reiniciar a exportação; tratar como XPZ gerado com diagnostico degradado, declarar o marco XPZ gerado no handoff e prosseguir para a materialização; classificação formal e governanca do sub-estado exportacao headless concluida e XPZ gerado (falha no pos-processamento do wrapper) pertencem a xpz-msbuild-import-export — esta skill apenas roteia para la quando houver duvidaB) com XPZ gerado, reproduzir no texto ao usuário os totais reais de packageInventory (totalObjects, totalAttributes, objectsByType, systemObjectsPresent, attributesTopLevelUnreconciled e inventoryWarnings quando existirem), exportErrors/invalidTypesRejected/knownStdOutNoise/exitCode/msBuildCategoryBBlocked no top-level do export.json quando existirem, e o operationalSubState; com exitCode=48 ou sub-estado exportação parcial com errors do MSBuild — artefato não confiável, PARAR — o XPZ não e entrega limpa; abrir package-inventory.json (via nominalInventoryAt, packageInventoryPath ou artifacts.PackageInventoryPath) sempre que extrasCount > 0, attributesTopLevelUnreconciled=true, ou systemObjectsPresent não vazio, e reproduzir a lista nominal completa por bloco — atributos top-level por nome somente quando attributesTopLevelUnreconciled=true; nunca resumir a rodada com a contagem de entradas de -ObjectList — governanca completa em xpz-msbuild-import-export (seção inventario após export seletivo)executionEvidence.msBuildExitCode, trata-lo como fonte canonica do exit bruto do MSBuild; msBuildExitCode top-level e compatibilidade transitoria e não deve substituir a leitura canonica nem a classificação da skill xpz-msbuild-import-exportGet-GeneXusKbProperty.ps1 do motor compartilhado está disponível via xpz-msbuild-import-export; seu uso e pontual e sob demanda — não faz parte de nenhuma etapa obrigatória do setupXPZ exportado pela IDEKbIntelligence como destino do SQLite derivado e dos relatórios de validaçãoscripts para consultar ou regenerar o índiceObjetosDaKbEmXml como fonte normativa e origem de regeneracao do índiceNomeCurto_GUID_YYYYMMDDXPZ exportado pela IDE:
XPZimport_file.xml e, quando aplicavel, XPZTransaction, Procedure, WebPanelFolder/ para objetos com Object/@type="00000000-0000-0000-0000-000000000008" (containers criados pelo usuário — "Pastas") e Module/ para objetos com Object/@type="00000000-0000-0000-0000-000000000006" (containers de sistema: Main Programs, ToBeDefined)ObjetosDaKbEmXml NÃO e indicador confiavel do tipo GeneXus entre KBs; a fonte autoritativa e sempre Object/@type no XML do objetoCliente.xml, GeraBoleto.xmlparentGuid, parentType e moduleGuid servem como metadados de apoio, não como estrutura principal de saidaObjetosGeradosParaImportacaoNaKbNoGenexus, usar a subpasta NomeCurto_GUID_YYYYMMDDPacotesGeradosParaImportacaoNaKbNoGenexus, usar o formato NomeCurto_GUID_YYYYMMDD_nn.import_file.xmlnn representa apenas a rodada curta do pacote naquela frente; não representa versão semanticaNomeCurto_GUID_YYYYMMDD somado ao nnReferencia rápida para decidir o peso operacional da ausencia de cada wrapper. As regras detalhadas de classificação (AUSENTE / EQUIVALENTE / CUSTOMIZADO) e os critérios de evidencia permanecem em 8.a e 8.g3; esta tabela e leitura rápida, não substituto.
| Wrapper | Obrigatório quando | Ausencia impede |
|---|---|---|
Test-*KbPowerShellRuntime.ps1 | sempre (primeiro gate de uso operacional) | qualquer uso operacional da pasta paralela |
Test-*KbObjetosDaKbNaming.ps1 | ObjetosDaKbEmXml materializado | wrappers_atualizados e materializado_e_indice_validado limpos |
Test-*KbSetupFreshness.ps1 | sempre (invocacao pelo gatilho global) | fast path da PRE-CONDICAO — ausente forca auditoria completa a cada invocacao do gatilho |
Set-*KbSetupAuditTimestamp.ps1 | recomendado quando last_setup_audit_run_at ou setup_contract_signature_* estiver ausente, invalido ou defasado após auditoria bem-sucedida | nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente ou a edicao manual seguir o passo 34 |
Update-*KbFromXpz.ps1 | sempre (fluxo oficial de materialização) | pronto_para_primeira_materializacao |
Test-*KbFullSnapshot.ps1 | sempre (fluxo oficial de materialização) | pronto_para_primeira_materializacao |
Query-*KbIntelligence.ps1 | KbIntelligence adotado | wrappers_atualizados |
Rebuild-*KbIntelligenceIndex.ps1 | KbIntelligence adotado | wrappers_atualizados |
Test-*KbIndexGate.ps1 | KbIntelligence adotado | wrappers_atualizados |
Get-*KbMetadata.ps1 | KbIntelligence adotado | wrappers_atualizados |
Resolve-*KbIdentity.ps1 | esperado no setup inicial/auditoria quando a pasta tem KB nativa local confirmada e precisa preencher ou conferir identidade estavel; recomendado nas demais reconciliacoes aprovadas em que o XPZ veio com Source vazio ou incompleto | metadata apto para empacotamento quando a identidade estavel estiver ausente, incompleta ou divergente |
Test-*KbMetadataWrapper.ps1 | KbIntelligence adotado | wrappers_atualizados |
Test-*KbStructure.ps1 | KbIntelligence adotado | wrappers_atualizados |
Test-*KbSetupAudit.ps1 | KbIntelligence adotado | wrappers_atualizados |
Test-*KbSourceSanity.ps1 | empacotamento local adotado | auditoria_de_empacotamento_pendente |
Test-*KbPackageCollision.ps1 | empacotamento local adotado | auditoria_de_empacotamento_pendente |
New-*KbFront.ps1 | recomendado quando agentes abrem frentes locais com frequência e precisam evitar comandos PowerShell compostos | nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente ou os passos atomicos forem executados separadamente |
Get-*KbLastUpdate.ps1 | recomendado quando agentes atualizam lastUpdate em XMLs locais com frequência e precisam evitar comandos PowerShell compostos | nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente ou o timestamp puder ser obtido por comando atômico |
New-*KbImportPackage.ps1 | recomendado quando o empacotamento local for recorrente e a KB precisar de comando curto/allowlist | nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente |
Notify-TaskComplete.ps1 | opcional | nenhum estado |
Test-*KbPowerShellRuntime.ps1, a pasta scripts deve prever pelo menos dois wrappers locais quando a pasta paralela da KB operar com fluxo oficial de materialização XML sobre o motor compartilhado:
.xpz, XML exportado ou pasta contendo o XML do pacoteVerifyOnly + FullSnapshotSource vazio ou incompleto, recomendar wrapper local fino Resolve-*KbIdentity.ps1:
scripts\Resolve-GeneXusKbIdentity.ps1 da base compartilhadamodel.ini, knowledgebase.connection e banco interno da KBkbGuid, kbName, versionGuid, versionName, UNCPath e username para apoiar preenchimento aprovado de kb-source-metadata.md-UpdateMetadata, delega para scripts\Update-XpzKbSourceMetadataIdentity.ps1, preenche campos ausentes de identidade estavel e bloqueia divergencias não vazias salvo aprovacao explicita para sobrescritaGet-*KbMetadata.ps1: resolve identidade a partir da KB nativa; Get-*KbMetadata.ps1 le o metadata já gravadoKbIntelligence, a pasta scripts também deve prever wrappers locais finos para:
KbIntelligence\kb-intelligence.sqliteObjetosDaKbEmXmlTest-*KbIndexGate.ps1): chama o wrapper de consulta local com -Query index-metadata, le kb-source-metadata.md, compara timestamps e retorna GATE_OK ou lanca BLOCK: <motivo>; depende de Query-*KbIntelligence.ps1 na mesma pasta; deve ser o único ponto de execução do gate de frescorkb-source-metadata.md (Get-*KbMetadata.ps1): elimina o padrão recorrente de Select-String + regex inline nos chamadores; expoe ao menos last_xpz_materialization_run_at, kb_name e source_guid
last_xpz_materialization_run_at: campo de topo ou frontmatter de kb-source-metadata.mdkb_name: campo name da tabela na seção ## Source/Version (nome da KB na IDE)source_guid: campo kb (GUID) da tabela na seção ## Source — GUID da KB, não o GUID da versão em ## Source/Version; implementacoes que lerem source_guid de ## Source/Version serao semanticamente incorretas mesmo com parse validoTest-*KbMetadataWrapper.ps1): chama o motor compartilhado Test-XpzKbMetadataWrapper.ps1, compara o que Get-*KbMetadata.ps1 expoe contra kb-source-metadata.md e retorna METADATA_WRAPPER_OK, METADATA_WRAPPER_INCOMPLETE, PENDENTE_DE_DADOS ou BLOCK: ...Test-XpzKbDeploymentMetadata.ps1, consolidada em Test-*KbSetupAudit.ps1 como metadata/deploy): rejeita metadata legado (tipico de scan por pastas web\), inconsistencias de contagem e mapeamento de output/web ausente ou divergente; não substitui pergunta ao usuário nem validação MSBuild de nomes declaradosObjetosDaKbEmXml (Test-*KbObjetosDaKbNaming.ps1): chama o motor compartilhado Test-XpzObjetosDaKbNaming.ps1, cobre todos os diretórios imediatos do snapshot, extrai o tipo real por raiz Attribute ou Object/@type, compara com o catalogo efetivo (gx-object-type-catalog.json + scripts/gx-object-type-catalog.override.json quando existir) e retorna NAMING_OK, NAMING_DIVERGENT ou NAMING_INDETERMINADO; não renomeia diretóriosTest-*KbStructure.ps1): relatório de presenca/ausencia de pastas, scripts e artefatos esperados; retorna STRUCTURE_OK ou lista componentes ausentes; usado no setup e em diagnostico antes de qualquer operacaoTest-*KbPowerShellRuntime.ps1): chama o motor compartilhado Test-XpzPowerShellRuntime.ps1, verifica existência de pwsh com PowerShell 7.4 LTS ou superior e bloqueia qualquer uso operacional da pasta paralela se retornar BLOCK:; deve ser o primeiro wrapper executado em setup, auditoria, frescor, sync, índice ou empacotamentoTest-*KbSetupAudit.ps1): chama o motor compartilhado Test-XpzSetupAudit.ps1, consolida evidencias deterministicas de powershell/runtime, sync/materializacao, naming/objetos-da-kb, indice/gate, indice/semantica, metadata wrapper, metadata/deploy, empacotamento local, declarativo/timestamps, wrappers/inventario e estado_operacional_sugerido; deve orquestrar os gates específicos, nunca substitui-los como evidencia primaria; quando -PowerShellRuntimeTestPath não for informado ao motor compartilhado, ele varre scripts/Test-*KbPowerShellRuntime.ps1, usa o wrapper único detectado e, se nenhum existir, emite powershell/runtime.detecao=missing, powershell/runtime.wrapper_sugerido e powershell/runtime.molde sem criar arquivo automaticamente; quando existir e a intencao operacional for auditar_setup, o agente deve executa-lo e usar sua saida consolidada como veiculo de handoff — as dimensoes do wrapper substituem a sintese manual dessas mesmas dimensoes, mas não substituem a evidencia dos gates específicos que as fundamentamObjetosGeradosParaImportacaoNaKbNoGenexus e PacotesGeradosParaImportacaoNaKbNoGenexus, recomendar também wrapper local fino para gate de Source, por exemplo Test-*KbSourceSanity.ps1:
-InputPath; -Path, quando aceito, e alias de compatibilidadescripts\Test-GeneXusSourceSanity.ps1 da base compartilhada-AsJson ao motor compartilhado: Test-GeneXusSourceSanity.ps1 já emite JSON por padrão e NÃO aceita -AsJson (trava confirmada por Test-XpzParameterNamingContract.ps1); o motor também espera um arquivo, não uma pasta — se o wrapper local precisar varrer varios XML ou montar JSON próprio, faz isso no wrapper sem propagar a flag para baixoxmlWellFormed, sourceSanityStatus e probablyImportablesourceSanityStatus=failwarn, devolve a lista de warnings e exige revisao conservadora antes do pacotePacotesGeradosParaImportacaoNaKbNoGenexus, recomendar também wrapper local fino para gate de colisao de pacote, por exemplo Test-*KbPackageCollision.ps1:
FrontPrefix, NN e OutputDir, ou PackagePath; -Path/-InputPath, quando aceitos, são alias de compatibilidade para PackagePathscripts\Test-XpzPackageCollision.ps1 da base compartilhadastatus=ok, reason=COLLISION_OK e exit 0 quando a rodada pretendida ainda não existestatus=bloqueado, reason=PACKAGE_ROUND_COLLISION, blockingReasons, nextFreeNN, nextFreeRound e exit 20 quando a rodada nn já existir para o mesmo prefixo de frenteObjetosGeradosParaImportacaoNaKbNoGenexus, recomendar wrapper local fino para abertura de frente, por exemplo New-*KbFront.ps1:
NomeCurto, opcionalmente ExtraGuidCount, ReuseIfExists e AsJsonscripts\New-GeneXusXpzFront.ps1 da base compartilhadaNomeCurto_GUID_YYYYMMDD em chamada atômicafrontGuid, yyyymmdd, frontDir, createdAtUtc, GUIDs adicionais e motivo de bloqueio quando aplicavelsame front ou new front; essa decisão continua pertencendo ao fluxo da xpz-builderNew-GeneXusXpzFront.ps1) é o passo que cria ou retoma a pasta da frente; popular (Copy-*KbAcervoToFront.ps1 / Copy-GeneXusAcervoToFront.ps1) e os gates que recebem -FrontFolder (9-FD Test-GeneXusFrontAcervoDrift.ps1 e os demais) operam sobre uma frente já existente e não criam a pasta — abrir a frente aqui, com -ReuseIfExists para retomar, antes de popular ou empacotar; criar a pasta manualmente é anti-padrão (o motor emite o erro FRENTE_NAO_ABERTA quando a frente não existe)lastUpdate em XMLs locais com frequência, recomendar wrapper local fino para timestamp, por exemplo Get-*KbLastUpdate.ps1:
Count, AsJson, baseline oficial e margem de frescorscripts\Get-GeneXusXpzLastUpdate.ps1 da base compartilhadayyyy-MM-ddTHH:mm:ss.0000000Zmax(UtcNow + margem, lastUpdate do baseline + margem), com margem padrão de 60 segundosmodified in this round vs reused unchanged for mandatory dependency closure; apenas fornece o instante canonico para objetos realmente alteradosimport_file.xml for recorrente, recomendar wrapper local fino para criacao do pacote, por exemplo New-*KbImportPackage.ps1:
FrontName, NN e opcionalmente TemplatePackagePath e AcervoPath (override do acervo; quando omitido, o motor resolve o acervo canonico <RepoRoot>/ObjetosDaKbEmXml da pasta paralela); a saida de maquina e JSON por padrão no stdout, sem -AsJsonscripts\New-XpzImportPackage.ps1 da base compartilhadascripts\New-XpzImportPackage.py (chamada direta ao .py não é rota operacional equivalente), le kb-source-metadata.md, resolve as pastas padrão da pasta paralela, classifica raizes Object/Attribute, executa sempre o gate de drift frente-vs-acervo 9-FD (Test-GeneXusFrontAcervoDrift.ps1) em modo fail-closed antes do empacotamento, executa o gate de colisao e monta o pacote; no gate 9-FD, -AcervoPath e opcional e, quando omitido, o acervo canonico <RepoRoot>/ObjetosDaKbEmXml e resolvido automaticamente — sem acervo resolvivel o empacotamento e bloqueado, e o JSON reporta acervoResolvedBy (explicit ou convention); bloqueios esperados voltam como JSON estruturado com status, exitCode, stage e blockingReasons, nunca como stack/ANSI para consumo de maquinaTemplatePackagePath for informado, o motor aceita import_file.xml ou .xpz real comparavel, clona KMW, Source, Dependencies, ObjectsIdentityMapping e, quando não houver Attribute explicito na frente, preserva também Attributes de topo do template; para Panel, um par level id/layout id localizado nesse template comparavel pode ser registrado como confirmado; quando omitido, usa envelope mínimo derivado de kb-source-metadata.md e retorna warning para pacote misto/complexo, com ressalva específica de par não verificado para Panelwrappers_atualizados enquanto a KB puder chamar o motor compartilhado diretamente com -RepoRoot.cs, por exemplo Resolve-*KbGeneratedCsPath.ps1:
KbPath, ObjectName, opcionalmente ObjectType, EnvironmentName e AsJsonscripts\Resolve-GeneXusGeneratedCsPath.ps1 da base compartilhadakb-source-metadata.md e usa kb_environment_web_dirs para montar <webDir>\<objectName-lowercase>.cs sem varredura recursiva da KB nativakb_environment_web_dirs estiver ausente ou sem o environment solicitado, retorna BLOCK e orienta executar xpz-kb-parallel-setup para reconciliar o metadata; não aceitar chute de diretório nem scan de C:\GxModelsdeployment_hosting_kind de família não-.NET (java-tomcat, Eixo B sourceSupportState=recognized-no-engine, Pós-v1 — o Eixo A roda o co-gate Java) retorna CS_PATH_SKIPPED_HOSTING_UNSUPPORTED (exit 0, sem csPath) antes do bloqueio de web_dirs — o skip não exige web_dirs (o artefato Java não é .cs)importação real efetiva provada, geração de runtime pendente ou o usuário reportar que o comportamento ainda não mudou após import e build, a checagem de frescor de runtime pode ser executada diretamente pelo script da base compartilhada scripts\Test-GeneXusRuntimeFreshness.ps1 — não requer wrapper local:
-KbPath (obrigatório): caminho da KB GeneXus nativa (onde reside nav_objs.xml)-ObjectName (obrigatório): nome do objeto GeneXus a verificar-ImportedAt (obrigatório): timestamp do import como linha de corte (string ISO parseable)-ObjectType (opcional): tipo GeneXus do objeto; reservado para uso futuro-GeneratorOutputPath (opcional): pasta de output do gerador; antes de informar este parâmetro para diagnostico de .cs em KB multi-environment, resolver o caminho com scripts\Resolve-GeneXusGeneratedCsPath.ps1/Resolve-*KbGeneratedCsPath.ps1 a partir de kb_environment_web_dirs; se omitido, o script legado deriva <KbPath>\CSharpModel\web, o que e apenas complementar e não substitui metadata de output por environment-DeploymentHostingKind (obrigatório em KB de família não-.NET quando conhecido, especialmente java-tomcat): passar java-tomcat para que o Eixo C pule com skipped-hosting-unsupported/exit 0 em vez de aplicar heurística .NET sobre nav_objs.xml e CSharpModel\web-AsJson (opcional): emite saída JSON estruturada em vez de texto humanoGenerates and clones GeneXus XPZ objects conservatively — validates structure, applies risk rules, serializes envelope
Valida o estado de uma pasta paralela de KB GeneXus antes do push (rotina pré-push de pasta paralela), rodando o orquestrador de gates mecânicos local do repositório ativo; não é a rotina pré-push do repositório de skills (documento 13)
Skill para importação e exportação de XPZ via MSBuild, com execução sem interface gráfica, parâmetros explícitos, rastreabilidade e gates (pontos de liberação ou bloqueio) de segurança
Permite ao agente principal delegar tarefas menores, pedir segunda opinião ou conduzir revisão por pares/peer review de plano/design por painel multi-modelo via opencode, Codex, Claude Code (Opus 4.8), GitHub Copilot CLI ou Gemini CLI; ao receber "revisão por pares", carregar esta skill, perguntar revisores preferidos se não houver preferred-reviewers.json, não presumir assinatura externa e nunca rotular parecer solo como revisão por pares; acionamento sempre humano
Skill para validação de build pós-import via MSBuild, com execução sem interface gráfica, parâmetros explícitos, classificação de resultado e gates de segurança contra reorg não autorizada
Backup auditável para aplicar patch textual Git já aprovado no Codex, em um repositório alvo, quando a rota nativa apply_patch estiver indisponível, falhar antes de escrita local ou for solicitada explicitamente.