菜单
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
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Generates 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)
Prepara e valida a estrutura inicial da pasta paralela da KB para carga inicial, sync de XPZ, índice derivado e artefatos de importação
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.
| name | xpz-msbuild-import-export |
| description | 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 |
Skill para operações de importação e exportação de XPZ do GeneXus por MSBuild, em execução sem interface gráfica.
Esta skill não substitui o fluxo oficial atual da trilha paralela da KB, não depende de GeneXus Server e não trata sucesso operacional como evidência suficiente de sucesso funcional.
No estado atual, o mecanismo central desta skill já foi validado operacionalmente em múltiplas KBs. O próximo passo desta frente não é mais provar exportação, PreviewMode e importação real como capacidade basal, e sim deixar explícitos:
Exceções já mapeadas que a skill deve tratar explicitamente:
XPZ, como KB_Teste_AGeneXus Server ou licença, como KB_Teste_EKB_Teste_Grande_AWebPanelDesigner/K2B Object DesignerCritério atual de prontidão operacional desta skill:
PreviewMode e importação real já validados em KBs de teste controladasXPZUso mais amplo desta skill ainda depende de:
Orquestre operações de XPZ via MSBuild com parâmetros explícitos, coleta rastreável de evidências e aborto seguro antes de operações sensíveis. Priorize descoberta de ambiente, PreviewMode, UpdateFile quando suportado pela task carregada, IncludeItems/ExcludeItems para recortes controlados e validação posterior. Nunca trate importação real como padrão.
Exceção — validação de
API(from-spec): oPreviewModeprioriza inspeção, mas não valida umaAPI— reportaimportTaskSuccess:truemesmo paraAPIinválida (valor de[SecurityLevel]inválido,Procedurede implementação ausente). Só a importação real roda a validação de gramática/referências daAPI(inclusive a resoluçãoAPI => Procedure). Quando o objetivo for validar umaAPIfrom-spec, usar importação real (empacotando aAPIcom seuProcedure, ou fazendo staging doProcedureantes) — a autorização de import real e os gates de envelope continuam valendo. Ver10-base-operacional-msbuild-headless.mdexpz-builder/responsibilities-by-type/api.md.
Limite da importação real em API: import real prova gramática e resolução de referência da API, mas não prova que o runtime servido reflete o import nem que o endpoint funciona. Quando a frente exige prova funcional de endpoint, registrar build/deploy aplicável e teste HTTP separado (método, rota, status, payload resumido, ambiente servido); isso também não substitui smoke GAM 401/403/200 quando segurança estiver em escopo.
SKILL.md fica em uma subpasta de skill sob a raiz do repositório.../arquivo.md relativas à pasta desta skill, não ao diretório corrente.../arquivo.md.../ aponta para a base metodológica compartilhada da raiz.Use esta skill para:
MSBuildKnowledge Base por OpenKnowledgeBaseEnvironment ativoPreviewModeUpdateFile, quando suportado pela task carregada, para análise prévia de impactoXPZ com parâmetros explícitosXPZ apenas em fase explicitamente autorizada de teste controladoGet*PropertyDo NOT use esta skill para:
GeneXus Server como requisito operacionalKbPath, versão, Environment ou parâmetros sensíveisMSBuild terminou sem erroSource, Rules ou CDATA de um objeto de KB — isso pertence ao xpz-builderKbPath, GeneXusDir, MsBuildPath, WorkingDirectory, LogPath e Genexus.Tasks.targets$env:PATH herdado com subdirs do GeneXus 18 (GeneXus18, gxnet, gxnet\bin, gxnetcore) antes de chamar MSBuild, registrando observedContext.pathEnrichment; isso é defesa de ambiente headless, não evidência de falha reproduzida em import/export puroTest-GeneXusMsBuildSetup.ps1 como probe (sondagem técnica inicial) não invasivo, anterior a qualquer abertura de KBC:\Program Files (x86) como estritamente somente leitura.msbuild e artefatos sejam gerados fora de C:\Program Files (x86)WorkingDirectory explicitamente informado, depois de validado como seguro e fora das áreas proibidasTemp como destino de artefatos efêmeros de execução e manter scripts como pasta de wrappers permanentesensaio metodológico/experimental, especialmente em casos de serialização, roundtrip controlado, prova de wrapper, prova de envelope, exportação headless, PreviewMode ou importação de teste sem validação funcional posteriorensaio metodológico/experimental, não narrar o resultado como mudança funcional validada; limitar a conclusão ao que a evidência realmente cobriustatus, summary, resolvedPaths, checks, blockingReasons, warnings e strategyTraceJSON como formato canônico inicial desse diagnósticostdoutSignals (campos semânticos por domínio), stderrContent, stderrFilteredNoise, exitCode, caminho do .msbuild temporário e caminho do log-FullExport do wrapper local quando ele existir; manter ExportAll='true' apenas como compatibilidade com contratos antigosPreviewMode e, quando suportado pela task carregada, UpdateFile antes de importação real quando import real ainda não foi autorizado na sessão ou a rodada for exploratória; com import real já autorizado e passos 6b–6c sem bloqueio, seguir Decisão pós-gates no WORKFLOW (preview não obrigatório; Invoke-GeneXusXpzImport.ps1 na mesma rodada)operação na KB de atualização do acervo oficialObjetosDaKbEmXmlXPZ, a atualização de ObjetosDaKbEmXml deve ocorrer depois, pelo fluxo de xpz-syncImportKBInformation, UpdateFile e defaults internos de importação/exportação como sensíveis e dependentes da assinatura efetiva da task ImportImportKbInformation como tri-state na chamada e no wrapper: omitido ou false significam não emitir o atributo na task (omissão do atributo faz a task aplicar seu próprio default, documentado como true em 10-base-operacional-msbuild-headless.md); apenas true emite e exige suporte na instalação atual. Quando o agente passar valor neutro (false) e a task não expuser a propriedade, o wrapper deve omitir o atributo, não bloquear; bloqueio por assinatura só vale para valor não neutro (true). O mesmo princípio se aplica a UpdateFile: omitido equivale a não emitir; valor não vazio em task sem suporte bloqueia.chamada corrigida por parâmetro sensível omitido.IncludeItems e ExcludeItems como lista antes de serializar para a task carregadaimportedItems como lista em qualquer diagnóstico JSON, mesmo quando houver apenas um itemimportação real efetiva provada apenas quando importedItems contiver explicitamente o objeto esperado; exitCode=0 com importedItems ausente ou vazio classifica como sucesso operacional sem prova de import efetivo — nunca como import concluídoInvoke-GeneXusXpzImport.ps1 lançar exceção interna durante o pós-processamento (ex: Exception calling Join, falha de serialização do import.json, qualquer falha posterior à conclusão da task Import do MSBuild) mas o log bruto (msbuild.stdout.log ou stdout capturado) contiver __IMPORTED_ITEM__ ou marca equivalente para o objeto esperado, classificar como importação real efetiva provada por evidência de stdout (falha no pós-processamento do wrapper) — nunca como falha operacional nem como sucesso operacional sem prova de import efetivo; a importação real aconteceu de fato, o que falhou foi a montagem do diagnóstico estruturado pelo wrapper; declarar explicitamente que importedItems veio do log bruto e que o import.json está degradado ou ausente; registrar a exceção do wrapper como degradação de diagnóstico separada, não como causa de falha de importUpdateFile nem ImportKBInformation em valor não neutro solicitado pelo agente, o wrapper de preview deve bloquear esses parâmetros cedo, com status preview bloqueado por assinatura da task; valor neutro (omissão de UpdateFile, ImportKbInformation=false) deve ser tratado como não emissão e não disparar bloqueioGet*Property como operação de leitura segura, sem efeito sobre a KBGetVersionProperty -Name Name como -VersionName em exportação ou importação; esse valor é o nome descritivo da versão (ex: "Design"), não o identificador aceito por SetActiveVersion (ex: "wsEducacaoSpTeste"); para obter o identificador compatível, usar GetActiveVersionGetEnvironmentProperty -Name Name como -EnvironmentName pelo mesmo motivo; usar GetActiveEnvironment para obter o identificador ativo compatívelSetActiveVersion ou SetActiveEnvironment falhar, tratar como bloqueio operacional explícito: a versão ou o Environment solicitado não existe na KB. O diagnóstico deve orientar omitir -VersionName ou -EnvironmentName para usar o contexto ativo, quando esse for o objetivo.-Level e -Name explicitamente antes de emitir a task; exigir -Target
quando -Level for Generator, DataStore ou Object-Name explícitoSource, Specification ou referência não resolvida em objeto importado, tratar a continuação como frente de conteúdo da KB/XPZ, não como ajuste adicional presumido do wrapperMecanismos de descarte de codigo de evento pelo gerador GeneXus: (a) rejeição na importação versus (b) strip silencioso por eliminação de código morto (DCE). A ação corretiva é diferente em cada caso; não tratar (b) como falha de import nem (a) como bug de runtime/build.exitCode != 0, errors presentes no import.json de Invoke-GeneXusXpzImport.ps1, ou mensagem no log/stdout com Unknown function '<nome>' / código src0294 (ou similar) apontando linha/coluna do evento, classificar como importação real falhou por source e registrar explicitamente que o padrão observado é rejeição na importação — função ou construção não exposta à camada de eventos GeneXus; o objeto não foi atualizado na KB. Ler a mensagem para identificar a função rejeitada; a correção é trocar a abordagem no source/XPZ, não reimportar o mesmo pacote nem investigar .cs gerado como causa primária.Transaction Rules + src0056: se a mensagem for src0056: Missed ';' at the end of the rule em Transaction Rules, não tratar como pontuação genérica — ver anti-padrão transaction-rule-on-event-with-attribute-parameter em 02-regras-operacionais-e-runtime.md e Catálogo 1 em xpz-builder/responsibilities-by-type/transaction.md. Antes de wirear reatividade per-attribute em rule declarativa de Transaction, consultar esse catálogo (escopo motor XPZ; gatilhos corretos GeneXus: skill nexa).importação real efetiva provada ou equivalente) mas o comportamento esperado do evento não aparece na UI, não classificar como falha de import nem presumir envelope/XML inválido; após build, buscar o handler no .cs gerado pelo nome do evento — zero ocorrências ou corpo vazio indica strip por DCE. Handoff para xpz-msbuild-build (inspeção do .cs) e para a seção canônica em 02; a correção típica é tornar o corpo do evento observável ao gerador (ex.: operação opaca via proc externa), não ajustar wrapper de import.Source global preenchido e outro teste controlado com ajuste isolado de Pattern Settings não mudarem o padrão principal do log, registrar explicitamente que essas diferenças deixaram de ser suspeitas fortes e estreitar a hipótese para conteúdo da KB/XPZ.xpz já existente («por que X está aí?», «tem Y nesse pacote?», «quais atributos exatamente?», «quais Domains?») — exigem fonte autoritativa antes de responder. Caminho A: na mesma rodada, ou quando o export.json da rodada ainda estiver acessível, reler package-inventory.json via packageInventory.nominalInventoryAt, packageInventory.packageInventoryPath ou artifacts.PackageInventoryPath. Caminho B: em sessão nova, ou quando o sidecar daquela rodada não existir mais (ex.: diretório efêmero em Temp já removido), executar Get-GeneXusImportPackageObjectInventory.ps1 -InputPath <xpz> direto sobre o .xpz. extrasSample, objectsByType e contagens do export.json são resumo amostral ou agregado; memória de conversa anterior também é amostral; a fonte autoritativa do conteúdo nominal é o sidecar (caminho A) ou nova execução do motor de inventário (caminho B).xpz/XML for um ExportFile legado GeneXus 9 (<GXObject><Elemento> por nome, sem GUID de tipo), Get-GeneXusImportPackageObjectInventory.ps1 detecta o perfil automaticamente e devolve legacyFormatDetected=true, itens typeStatus="known-legacy" (type = tipo moderno para equivalent ou gxlegacy/<Elemento> para orphan), unknownTypeCount=0 e unknownTypesDiscovery=[] — não confundir esse 0/[] com "zero tipos desconhecidos verificados" do fluxo moderno: o fail-closed de tag desconhecida vive no parser legado. Pacote misto (legado + moderno no mesmo ExportFile) é BLOCK (fail-closed). O contrato moderno de inventário (params, exit, shape de decisão) é inalterado. Regra operacional dona: 02-regras-operacionais-e-runtime.md; representação: 01k-registro-elementos-legados.md; materialização: xpz-sync/SKILL.md (seção EXPORTS LEGADOS)Responda no idioma do usuário
Seja direto sobre estado operacional, riscos e limites
Declare quando o resultado é apenas operacional e ainda depende de confirmação funcional
Em operações de import, declare o sub-estado explicitamente pelo nome (importação real efetiva provada, importação real efetiva provada por evidência de stdout (falha no pós-processamento do wrapper), sucesso operacional sem prova de import efetivo, importação real efetiva provada, efeito não confirmado na IDE, importação real efetiva provada, geração de runtime pendente, importação real falhou por source, etc.) — não deixe o leitor inferir o nível de prova a partir do relato narrativo
Quando o usuário quiser evidência complementar além de importedItems, apresentar as duas opções em paralelo: acionar xpz-msbuild-build (headless) ou abrir a KB na IDE e executar o build por lá — ambas são opcionais e o resultado do build não reescreve nem substitui o sub-estado de import já declarado
Quando o sub-estado for importação real efetiva provada, build tiver sido executado e o usuário reportar que o comportamento ainda não mudou, oferecer explicitamente a checagem de frescor de runtime como próximo passo nomeado antes de sugerir nova edição; declarar nominalmente o que será verificado no motor atual .NET: nav_objs.xml (ObjStatus=genreq é tratado como geração pendente pelo diagnóstico .NET; ObjStatus=nogenreq indica gerado) e timestamps dos artefatos gerados (.cs, .aspx ou equivalente); NVG fica excluído desse motor .NET atual por não ser arquivo estático acessível sem abrir a IDE. Em KB java-tomcat, passar -DeploymentHostingKind java-tomcat: o Eixo C pula com skipped-hosting-unsupported/exit 0, e ObjStatus não deve ser usado isoladamente como critério de freshness Java; o futuro motor Java deve cruzar ObjNavig, XMLs de navegação/specification e artefatos locais. Se a checagem aplicável indicar artefatos de versão anterior, classificar como importação real efetiva provada, geração de runtime pendente e propor reabertura + rebuild antes de qualquer nova edição
Quando import OK mas evento não reflete na UI ou no .cs gerado, declarar explicitamente que isso não reabre sub-estado de import — tratar como hipótese de mecanismo (b) e orientar inspeção pós-build do .cs ou handoff para xpz-msbuild-build, conforme seção Mecanismos de descarte de codigo de evento pelo gerador GeneXus em 02-regras-operacionais-e-runtime.md
Quando a rodada for ensaio metodológico/experimental, declarar isso nominalmente no resumo e separar:
Quando a rodada envolver iteração sobre objeto único, consolidar o resultado no seguinte template antes de recomendar próximo passo:
Rodada N — <NomeDoObjeto> (<TipoObjeto>)
- XML local atualizado: sim / não
- XML bem-formado: sim / não
- Sanity: limpo / warnings / bloqueante
- Preview: reconhecido / não reconhecido / não executado
- Import real: <sub-estado nomeado>
- Warnings conhecidos: <lista ou "nenhum">
Quando houver ambiguidade de contexto, interrompa a execução e peça definição explícita
Não use linguagem otimista para sugerir segurança que ainda não foi validada empiricamente
Quando a exportação headless gerar um .xpz para alimentar a pasta paralela da KB, declarar explicitamente o marco XPZ gerado
Se a geração do .xpz fizer parte do caminho B do setup inicial, diferenciar explicitamente a fase exportação headless concluída da fase posterior materialização em ObjetosDaKbEmXml
Se o pedido do usuário for apenas gerar o .xpz, parar no artefato gerado; só prosseguir para materialização quando o pedido for seguir com o setup ou com a materialização
Em exportação seletiva com -ObjectList, a presença de -ObjectList classifica a rodada como seletiva/cirúrgica para fins de sub-estado e de confronto de extras; nunca reportar ao usuário a contagem de entradas de -ObjectList como se fosse a contagem do pacote — a contagem comunicada é sempre a real do .xpz (packageInventory.totalObjects / totalAttributes e objectsByType, ou inspeção manual equivalente)
Em exportação seletiva/cirúrgica cujo objetivo declarado seja obter somente os itens de -ObjectList, passar -DependencyType "None" -ReferenceType "None" por padrão operacional; isso previne o arrasto na origem e não substitui o inventário pós-export. Se o usuário pedir dependências/referências, declarar que a rodada deixou de ser pacote estritamente nominal antes de executar e continuar exigindo inventário completo.
Quando export.json trouxer packageInventory, reproduzir no relatório ao usuário antes de declarar o XPZ como conclusão limpa: totais reais, objectsByType, systemObjectsPresent, attributesTopLevelUnreconciled / inventoryWarnings quando existirem; em export seletiva com extrasCount > 0, listar todos os extras do bloco <Objects> por nome (Tipo:Nome) — com extrasCount <= 50 podem estar em extrasSample; com extrasSampleTruncated=true ou para lista nominal completa abrir nominalInventoryAt / extrasFullListAt / packageInventoryPath / artifacts.PackageInventoryPath e ler package-inventory.json; com attributesTopLevelUnreconciled=true, listar cada atributo top-level do bloco <Attributes> por nome (não só totalAttributes); extrasSample cobre somente extras de objeto no resumo JSON e não substitui a comunicação nominal completa do pacote ao humano — não basta o campo existir só no JSON; quando exportErrors, invalidTypesRejected ou knownStdOutNoise (top-level) estiverem presentes, reproduzi-los também no texto ao usuário
Arquivos de referência e quando carregar:
| Referência | Carregar quando |
|---|---|
| README.md | Sempre - regras editoriais e posicionamento da base |
| 02-regras-operacionais-e-runtime.md | Regras operacionais, precedência e restrições da trilha XPZ; carregar também quando import falhar em código de evento (Unknown function/src0294) ou quando import OK mas evento não aparecer no .cs/UI (mecanismos de descarte do gerador) |
| 10-base-operacional-msbuild-headless.md | Sempre - base operacional, riscos conhecidos e interface vigente |
| xpz-msbuild-build/SKILL.md | Handoff quando import OK mas evento não aparece no .cs/UI (mecanismo b), quando o usuário pedir build/specify como evidencia complementar, ou para checagem de frescor de runtime após import — sem reabrir sub-estado de import |
Esta skill assume, como interface operacional, scripts pequenos e explicitamente parametrizados. Test-GeneXusMsBuildSetup.ps1, Open-GeneXusKbHeadless.ps1, Test-GeneXusXpzImportPreview.ps1, Invoke-GeneXusXpzExport.ps1, Invoke-GeneXusXpzImport.ps1, Invoke-GeneXusXpzImportThenBuild.ps1, Read-MsBuildImportSignals.ps1, Test-MsBuildImportSignalsClassifier.ps1, Extract-XpzObject.ps1, Get-GeneXusObjectSummary.ps1, Compare-GeneXusPanelShape.ps1, Test-GeneXusKbConsistency.ps1, Test-GeneXusImportFileEnvelope.ps1, Get-GeneXusImportPackageObjectInventory.ps1, GeneXusMsBuildStderrNoiseSupport.ps1, GeneXusMsBuildWatcherSupport.ps1, Watch-GeneXusMsBuildLog.ps1, Resolve-GeneXusGeneratedCsPath.ps1 e Test-GeneXusRuntimeFreshness.ps1 já foram materializados nesta fase; os demais não devem ser tratados como já implementados sem confirmação explícita. Os motores de montagem de import_file.xml referenciados no fluxo preferido (Build-GeneXusImportFileEnvelope.ps1 para montagem direta a partir de XMLs de objeto e template clonável, New-XpzImportPackage.ps1 como wrapper PowerShell seguro do motor interno Python New-XpzImportPackage.py para montagem por frente da pasta paralela) também estão materializados em scripts/ e são cobertos pela skill xpz-builder e pelas regras operacionais em 02-regras-operacionais-e-runtime.md; quando esta skill aponta para eles (anti-padrão de export-casca, inventário pré-import), trata-se de uso operacional vigente, não de promessa aspiracional. Ao usar Build-GeneXusImportFileEnvelope.ps1, -AcervoPath <ObjetosDaKbEmXml> é obrigatório; o motor bloqueia antes da gravação quando houver lastUpdate inválido contra o acervo ou Object/@type divergente por mesmo guid, preservando o bloco frontObjectTypeDrift com objectGuid normalizado, acervoPath/candidateAcervoPaths e message; objetos realmente modificados devem ser declarados por -ModifiedObjectNames ou -ModifiedObjectGuids para acionar o bloqueio mecânico de lastUpdate velho, igual ao acervo ou futuro sem justificativa.
Estado atual da materialização:
Test-GeneXusMsBuildSetup.ps1: implementado como probe (sondagem técnica inicial) não invasivoOpen-GeneXusKbHeadless.ps1: implementado para abertura e fechamento controlados da KB, com contexto ativo e sem import/exportTest-GeneXusXpzImportPreview.ps1: implementado para PreviewMode de importação e já validado nesta conversa com XPZ realInvoke-GeneXusXpzExport.ps1: implementado para exportação headless de XPZ com parâmetros explícitos e diagnóstico JSONInvoke-GeneXusXpzImport.ps1: implementado para importação real de XPZ com parâmetros explícitos e diagnóstico JSONInvoke-GeneXusXpzImportThenBuild.ps1: implementado como wrapper integrador de import real seguido de BuildAll pós-import; executa o build somente quando o JSON de import está apto (exitCode=0, sem blockingReasons, sem msBuildCategoryBBlocked e sem status de falha/bloqueio); parâmetros de build amplo/caro continuam sujeitos aos gates do wrapper receptor (-ForceRebuild exige -AllowWideRebuild, CompileMains=true ou DetailedNavigation=true exigem -AllowCostlyBuildOptions, com confirmações explícitas quando aplicável)Read-MsBuildImportSignals.ps1: implementado para leitura compacta de msbuild.stdout.log/msbuild.stderr.log, com importedItems, expectedItemsRaw/importedItemsRaw, expectedItemsCanonical/importedItemsCanonical, itemAliasMatches, warnings, erros, ruídos conhecidos de stdout, gxImportLogReadStatus/gxImportLogReadError, versão/Environment ativos, sucesso da task Import e warnings de layout agrupados por PanelTest-MsBuildImportSignalsClassifier.ps1: implementado como bateria mínima de validação do leitor compacto (ruído conhecido de CssProperties.json, lock de GxImport.log, equivalência Panel/SDPanel em itemAliasMatches); ver também 09-inventario-e-rastreabilidade-publica.mdExtract-XpzObject.ps1: implementado para extrair um objeto específico de XML/XPZ ou retornar resumo JSON sem imprimir o pacote inteiroGet-GeneXusObjectSummary.ps1: implementado para resumir objeto GeneXus e, para Panel, expor shape compacto de level/layout, controles, gridData, actions, eventos serializados em detail/@events, actionEventCoverage, namedEventNames, standardEventNames, variableEventNames e tapEventNames, e, para WebPanel classico, o bloco webpanel (tables com tableType Flex/Responsive e depth, controls, buttons em <action> e <ucw> Button, eventNames, coverage), sem despejar CDATACompare-GeneXusPanelShape.ps1: implementado para comparar dois Panels por shape compacto, incluindo Object attrs, Pattern/Data version, level/layout, controles, eventos serializados classificados (namedEventNames, standardEventNames, variableEventNames, tapEventNames) e cobertura action/eventTest-GeneXusKbConsistency.ps1: implementado como wrapper de CheckKnowledgeBase com diagnóstico JSON, classificação das categorias empíricas documentadas e confirmação interativa obrigatória para Fix="true"Test-GeneXusImportFileEnvelope.ps1: implementado para validação estrutural estática do import_file.xml antes de qualquer chamada ao MSBuild; não invasivo, não abre KBGet-GeneXusImportPackageObjectInventory.ps1: inventário determinístico de import_file.xml, XML com raiz <ExportFile> ou .xpz (XML interno único); lista <Object> sob <Objects>, Attribute top-level sob <Attributes>, agrega objectsByType, detecta objetos de plataforma/SDK via scripts/gx-platform-objects.json (Get-SystemObjectsPresent → systemObjectsPresent), sinal attributes-top-level-em-export-cirurgico em export seletiva sem Transaction na lista declarada, e confronta delta declarado (-DeclaredDeltaPath ou -DeclaredDeltaItems no formato Tipo:Nome, separador ; ou linha)Invoke-GeneXusXpzExport.ps1: após exportação com XPZ gerado, embute packageInventory resumido no diagnóstico e grava sempre package-inventory.json completo no diretório de artefatos da rodada; o resumo expõe nominalInventoryAt (lista nominal completa no sidecar) sempre que o sidecar for gravado; extrasSample (extras de <Objects> quando extrasCount ≤ 50), extrasSampleTruncated quando extrasCount > 50 (omissão de extrasSample no resumo); em export seletiva com confronto de delta, extrasFullListAt aponta para o mesmo sidecar (lista completa de extras de <Objects>); atributos top-level não entram em extrasSample; falha de inventário marca inventoryDegraded=true sem rebaixar exitCode da task MSBuild; regressão mínima do contrato resumido: scripts/Test-GeneXusPackageInventorySupportSelfTest.ps1 (sentinela GENEXUS_PACKAGE_INVENTORY_SUPPORT_SELFTEST_OK)GeneXusMsBuildStderrNoiseSupport.ps1: implementado como helper comum para separar ruído estrutural conhecido de stderr (stderrFilteredNoise) de erro real (stderrContent) nos wrappers de build e nos wrappers headless desta skill que expõem esse campo; pares cruzados ou linhas não documentadas permanecem como stderr realGeneXusMsBuildWatcherSupport.ps1: implementado como helper comum do contrato de watcher dos wrappers MSBuild; centraliza -StartWatcher, -MonitorLogPath, watcherContext, timing.phases e leitura do log do monitorWatch-GeneXusMsBuildLog.ps1: implementado como monitor incremental de execução headless; usar em preview/import/export grandes para acompanhar o MSBuild sem depender do chat; em importação real de pacote amplo ou com muitos WorkWithForWeb, usar watcher como padrão operacional recomendadoResolve-GeneXusGeneratedCsPath.ps1: implementado como resolvedor somente leitura do .cs gerado a partir de kb_environment_web_dirs em kb-source-metadata.md; usar antes de Test-GeneXusRuntimeFreshness.ps1 quando a checagem exigir -GeneratorOutputPath; exceção Fase 2 (guarda de família do Eixo B): KB java-tomcat/família não-.NET pula com CS_PATH_SKIPPED_HOSTING_UNSUPPORTED/exit 0, sem exigir web_dirs (o artefato Java não é .cs)Test-GeneXusRuntimeFreshness.ps1: implementado como diagnóstico somente leitura de frescor de runtime no motor .NET; usar quando o sub-estado for importação real efetiva provada, geração de runtime pendente para confirmar se artefatos de runtime já refletem a versão importada. Em KB java-tomcat, passar -DeploymentHostingKind java-tomcat: o Eixo C pula com skipped-hosting-unsupported/exit 0, e ObjStatus não deve ser usado isoladamente como critério de freshness JavaScripts nesta frente:
Test-GeneXusMsBuildSetup.ps1
MsBuildPath quando omitido: vswhere.exe e catálogo estático em scripts/GeneXusMsBuildPathContract.ps1; JSON inclui msBuildProbe (resolutionSource, vsWhere, candidates[])Test-GeneXusMsBuildDiscoveryContract.ps1
Open-GeneXusKbHeadless.ps1
status, summary, exitCode, executionEvidence, stage, requestedContext, observedContext, artifacts, stderrContent, blockingReasons, warnings, strategyTrace, msBuildExitCode top-level como compatibilidade transitória quando existir, e caminhos dos logsTest-GeneXusXpzImportPreview.ps1
PreviewMode sem importação real, com IncludeItems e ExcludeItems validados nesta instalaçãoimportedItems e serializa o diagnóstico JSON deve ser envolvido em try/catch; em caso de exceção interna (ex: Exception calling Join por entrada inesperada, falha de serialização, qualquer erro posterior à conclusão da task Import do MSBuild em modo preview), o script não deve perder a evidência já coletada — deve emitir um diagnóstico parcial contendo no mínimo: executionEvidence.msBuildExitCode como local canônico do valor bruto da task MSBuild, msBuildExitCode top-level apenas como compatibilidade transitória quando existir, exitCode classificado pelo wrapper, caminho do msbuild.stdout.log, lista de marcas __IMPORTED_ITEM__ extraídas diretamente do log bruto antes da exceção (quando disponível), marca explícita postProcessingFailed=true, diagnosticDegraded=true, mensagem da exceção e indicação de que importedItems deve ser confirmado por leitura do log bruto; quando executionEvidence.msBuildExitCode=0 e o preview não tiver alterado a KB, o status emitido é preview apenas com falha no pos-processamento e o sub-estado equivalente é preview concluído sem alterar a KB (falha no pós-processamento do wrapper) — não é falha operacional; nunca substituir executionEvidence.msBuildExitCode por código de exceção do PowerShell, nem rebaixar o exitCode classificado — ambos são evidência primária de que a task de import em modo preview concluiumsbuild.import.signals.json ao lado dos logs brutos sempre que possível, consumindo Read-MsBuildImportSignals.ps1; quando a leitura compacta conseguir executar, o diagnóstico JSON também deve embutir o objeto parseado em compactSignals; falha nessa leitura degrada o diagnóstico, mas não reclassifica a task Import como falha operacional quando executionEvidence.msBuildExitCode e stdout indicarem conclusãoInvoke-GeneXusXpzExport.ps1
__EXPORTED_FILE__, __OPEN_OUTPUT__, GetActiveVersion, GetActiveEnvironment e gxWarnings, e serializa o diagnóstico JSON deve ser envolvido em try/catch; em caso de exceção interna (ex: Exception calling Join por entrada inesperada, falha de serialização, qualquer erro posterior à conclusão da task Export do MSBuild), o script não deve perder a evidência já coletada — deve emitir um diagnóstico parcial contendo no mínimo: executionEvidence.msBuildExitCode como local canônico do valor bruto da task MSBuild, msBuildExitCode top-level apenas como compatibilidade transitória quando existir, exitCode classificado pelo wrapper, caminho do msbuild.stdout.log, valor do marcador __EXPORTED_FILE__ quando o stdout já estiver lido, marca explícita postProcessingFailed=true, mensagem da exceção e indicação de que o caminho do XPZ exportado deve ser confirmado por existência do arquivo e leitura do log bruto; quando executionEvidence.msBuildExitCode=0 e o arquivo XPZ existir, o status emitido é sucesso operacional com falha no pos-processamento e o sub-estado equivalente é exportação headless concluída e XPZ gerado (falha no pós-processamento do wrapper) — não é falha operacional; nunca substituir executionEvidence.msBuildExitCode por código de exceção do PowerShell, nem rebaixar o exitCode classificado — ambos são evidência primária de que a task de export concluiuInvoke-GeneXusXpzImport.ps1
importedItems e serializa o diagnóstico JSON deve ser envolvido em try/catch; em caso de exceção interna (ex: Exception calling Join por entrada inesperada, falha de serialização, qualquer erro posterior à conclusão da task Import do MSBuild), o script não deve perder a evidência já coletada — deve emitir um diagnóstico parcial contendo no mínimo: executionEvidence.msBuildExitCode como local canônico do valor bruto da task MSBuild, msBuildExitCode top-level apenas como compatibilidade transitória quando existir, exitCode classificado pelo wrapper, caminho do msbuild.stdout.log, lista de marcas __IMPORTED_ITEM__ extraídas diretamente do log bruto antes da exceção (quando disponível), marca explícita postProcessingFailed=true, diagnosticDegraded=true, mensagem da exceção e indicação de que importedItems deve ser confirmado por leitura do log bruto; o agente que consumir esse diagnóstico parcial aplica o sub-estado importação real efetiva provada por evidência de stdout (falha no pós-processamento do wrapper) quando o log bruto contiver evidência do objeto esperado, conforme regra em RESPONSIBILITIES; nunca substituir executionEvidence.msBuildExitCode por código de exceção do PowerShell, nem rebaixar o exitCode classificado — ambos são evidência primária de que a task de import concluiumsbuild.import.signals.json ao lado dos logs brutos sempre que possível, consumindo Read-MsBuildImportSignals.ps1; quando a leitura compacta conseguir executar, o diagnóstico JSON também deve embutir o objeto parseado em compactSignals; importedItems pode ser preenchido a partir desses sinais quando a montagem principal vier vazia por degradação do diagnósticoInvoke-GeneXusXpzImportThenBuild.ps1
BuildAll pós-import com parada condicionalstatus/roundtripStatus, summary, exitCode, importJson, buildJson, importReadyForBuild, buildSkippedReason, importProcess, buildProcess, resolvedPaths, artifacts, blockingReasons, warnings e strategyTraceInvoke-GeneXusXpzImport.ps1 falhar, bloquear, produzir Categoria B, não gravar JSON interpretável ou retornar status de falha/bloqueio, Invoke-GeneXusKbBuildAll.ps1 não é chamado; reportar buildJson=null e explicar em buildSkippedReasonroundtripStatus é roundtrip-ok somente quando o processo filho retorna exitCode=0; recovery degradado do BuildAll propaga o exitCode classificado, portanto Categoria B, reorg, timeout, MSBuild não-zero ou evidência incompleta resultam em build-failed-or-blocked, sem falso sucesso do roundtrip. O contrato detalhado de recovery pertence a xpz-msbuild-build.-AllowWideRebuild/-ConfirmWideRebuild, -AllowCostlyBuildOptions/-ConfirmCostlyBuildOptions e -AllowReorg/-ConfirmReorg são apenas repassados ao Invoke-GeneXusKbBuildAll.ps1; a autorização humana e as frases exatas continuam sendo responsabilidade do chamador conforme xpz-msbuild-build-PostImportDeployValidation, -StrictDeployBinCheck e -SkipDeployBinCheck também são apenas repassadas ao Invoke-GeneXusKbBuildAll.ps1 (checagem de publicação no destino do environment — web\bin no .NET; para java-tomcat, co-gate Java no WEB-INF\classes externo — gate com exit 49 quando ativo) — categoria distinta dos gates de autorização acima: são opções de validação, não têm frase exata nem par -Confirm* e não exigem autorização humana; contrato do gate em xpz-msbuild-buildRead-MsBuildImportSignals.ps1
-Path (diretório de artefatos ou stdout), -StdOutPath, -StdErrPath, -ExpectedItems, -Stage, -OutputPath, -AsJsonimportedItems, expectedItemsRaw/importedItemsRaw, expectedItemsCanonical/importedItemsCanonical, itemAliasMatches, warnings, errors, knownStdOutNoise, gxImportLogReadStatus/gxImportLogReadError, diagnosticDegraded, activeVersion, activeEnvironment, importTaskSuccess, layoutWarnings agrupados por Panel e contadores compactosknownStdOutNoise deve registrar mensagens conhecidas de ambiente no stdout sem promovê-las a erro; o caso cssproperties-access-denied cobre O acesso ao caminho 'C:\Program Files (x86)\GeneXus\GeneXus18\CssProperties.json' foi negado., quando a rodada também preserva evidência de sucesso (Bem sucedido, Import Task Sucesso ou marcador equivalente)Test-MsBuildImportSignalsClassifier.ps1
Read-MsBuildImportSignals.ps1 sem abrir KBExtract-XpzObject.ps1, Get-GeneXusObjectSummary.ps1, Compare-GeneXusPanelShape.ps1
Part/identidade/shape e comparar Panels exportados pela IDE contra Panels gerados localmenteTest-GeneXusKbConsistency.ps1
Fix="true" exige confirmação interativaTest-GeneXusImportFileEnvelope.ps1
pwsh 7.4 ou superior; o script declara #requires -Version 7.4 e Windows PowerShell 5.1 não é runtime suportadoimport_file.xml antes de qualquer chamada ao MSBuild; não invasivo, não abre KB, não requer GeneXus instalado-InputPath (caminho do import_file.xml)-PanelReferencePath (objeto ou pacote XML/XPZ comparável usado para confirmar par level id/layout id em Panel)status (apto para prosseguir | apto com ressalvas | não apto para prosseguir), checks (mapa de verificações individuais), objectCount, blockingReasons, warnings, information<ExportFile>; blocos obrigatórios <KMW>, <Source>, <Objects>, <Dependencies>; ausência de declaração XML interna dentro de <Objects>; ausência de texto solto ou placeholder literal em <Objects>; GUIDs válidos por objeto; Source/@kb e Source/Version/@guid em formato GUID-PanelReferencePath, Panel retorna panel-level-layout-unverified como ressalva; com referência que contenha o mesmo par, retorna panel-level-layout-confirmed apenas em information; referência informada sem par correspondente retorna panel-level-layout-suspiciousSource/@kb do pacote/template deve corresponder a essa KB. Divergencia indica pacote de outra KB e bloqueia automacao por agente; encaminhar para avaliacao/importacao manual pela IDE, conforme 02-regras-operacionais-e-runtime.md.Get-GeneXusImportPackageObjectInventory.ps1
import_file.xml, XML com raiz <ExportFile> ou .xpz (XML interno único)Objects, Attributes top-level, tipos mapeados, GUIDs e confronto opcional com delta declarado-InputPath (import_file.xml, XML equivalente ou .xpz)-DeclaredDeltaPath, -DeclaredDeltaItems, -FailOnDeltaMismatch, -CatalogPath, -SystemModulesCatalogPath, -SystemExternalObjectsCatalogPathimport_file.xml, não fabricar .xpz só para validar — chamar o motor direto sobre o import_file.xmlWatch-GeneXusMsBuildLog.ps1
-Pid, -LogPath-MonitorLog, -IntervalSeconds (default 5), -SilenceThresholdSeconds (default 120)GeneXusMsBuildWatcherSupport.ps1
watcherContext/timing.phases com o mesmo contratoGeneXusMsBuildStderrNoiseSupport.ps1
stderrFilteredNoise, preservando erros reais em stderrContent; consumido por import/export/preview e demais wrappers headless desta skillTest-GeneXusRuntimeFreshness.ps1
-KbPath, -ObjectName, -ImportedAt-ObjectType (reservado para uso futuro), -GeneratorOutputPath (se omitido, deriva como <KbPath>\CSharpModel\web), -DeploymentHostingKind (guarda de família do Eixo C; compatível com chamadas legadas, mas obrigatório operacionalmente quando a KB for de família não-.NET conhecida, especialmente java-tomcat, para obter skipped-hosting-unsupported em vez de rodar a heurística .NET), -AsJsonruntime-fresh (nogenreq + artefatos posteriores ao import, no motor .NET), runtime-stale (genreq ou artefatos anteriores, no motor .NET), runtime-unknown (objeto não encontrado em nav_objs.xml ou artefatos não localizados), skipped-hosting-unsupported (Fase 2 — quando -DeploymentHostingKind é java-tomcat/família não-.NET: pula sem derivar CSharpModel\web, exit 0; valor fora do registro → runtime-hosting-kind-invalido, exit não-zero; ObjStatus não é critério isolado de freshness Java)Get-GeneXusKbProperty.ps1
-KbPath, -Level (KB | Version | Environment | Generator | DataStore | Object), -Name, -WorkingDirectory, -LogPath-Target (obrigatório quando -Level for Generator, DataStore ou Object; nome do generator, datastore ou objeto), -GeneXusDir, -MsBuildPath, -VersionName, -EnvironmentName, -VerboseLogstatus (leitura concluída | falha de leitura), level, target (quando aplicável), propertyName, propertyValue, exitCode, executionEvidence, blockingReasons, warnings, strategyTrace, msBuildExitCode top-level como compatibilidade transitória quando existir, e caminho do logGetKnowledgeBaseProperty, GetVersionProperty, GetEnvironmentProperty, GetGeneratorProperty (parâmetro opcional Generator), GetDataStoreProperty (parâmetro opcional DataStore), GetObjectProperty (parâmetro Object obrigatório); todas expõem Name e PropertyValue como interface comumGetVersionProperty -Name Name retorna o nome descritivo da versão (ex: "Design"), não o identificador aceito por SetActiveVersion (ex: "wsEducacaoSpTeste"); GetEnvironmentProperty -Name Name tem a mesma incompatibilidade com SetActiveEnvironment; para obter o identificador compatível com essas tasks de posicionamento, usar GetActiveVersion e GetActiveEnvironmentContrato inicial específico de Test-GeneXusMsBuildSetup.ps1:
-WorkingDirectory, -LogPath-GeneXusDir, -MsBuildPath, -KbPath, -VerboseLog-WorkingDirectory continua explícito; quando o caminho seguro ainda não existir, o probe pode criar exatamente essa pasta e registrar isso no diagnósticoMsBuildPath quando omitido: vswhere.exe (-all -sort, componente MSBuild, Current\Bin antes de amd64) e, em seguida, catálogo estático em scripts/GeneXusMsBuildPathContract.ps1 (Visual Studio 18/2022/2019, Program Files e Program Files (x86)); detalhes e exemplo JSON em 10-base-operacional-msbuild-headless.mdmsBuildProbe (resolutionSource, vsWhere, candidates[] com path/source/exists/selected) além de strategyTracescripts/Test-GeneXusMsBuildDiscoveryContract.ps10 para apto para prosseguir10 a 16 para bloqueios operacionais esperados com diagnóstico estruturado90 para falha interna do script antes de diagnóstico completoParâmetros transversais esperados:
-KbPath-GeneXusDir-MsBuildPath-VersionName-EnvironmentName-WorkingDirectory-LogPath (caminho de arquivo de log onde o wrapper grava o JSON de resultado; apontar para um diretório existente é bloqueado cedo com exit 50 — gate fail-fast parametro-invalido, antes de abrir a KB; motor scripts/GeneXusMsBuildLogPathSupport.ps1)-VerboseLog-StartWatcher (quando suportado pelo wrapper, dispara Watch-GeneXusMsBuildLog.ps1 antes do MSBuild; requer -MonitorLogPath; ausência de -MonitorLogPath deve bloquear cedo por política com exit 46)-MonitorLogPath (caminho do log próprio do watcher; quando existir, alimenta timing.phases)-WatcherIntervalSeconds (default 5; intervalo válido: 1-60)-WatcherSilenceThresholdSeconds (default 120; intervalo válido: 30-3600)O contrato de watcher acima vale para Test-GeneXusXpzImportPreview.ps1,
Invoke-GeneXusXpzExport.ps1 e Invoke-GeneXusXpzImport.ps1. Ele é centralizado em
scripts/GeneXusMsBuildWatcherSupport.ps1; ao evoluir watcher, timing ou
watcherContext, manter o helper comum como sede da regra e evitar lógica divergente
dentro dos wrappers.
Parâmetros específicos de exportação:
-XpzPath-ObjectList (nome canônico da seleção por nome; sinônimo aceito -ObjectNames; tipo [string[]], aceita string única com lista ou array) — lista de objetos para exportação seletiva; para múltiplos objetos, separar entradas com ponto-e-vírgula (;) no formato Tipo:Nome; exemplo: Procedure:ProcA;WebPanel:WPB;Transaction:TrC; o prefixo Tipo deve ser o rótulo aceito pela task Export, não necessariamente o nome do tipo no catálogo interno nem o retorno de KbIntelligence — ver 10a-gx-export-task-labels.md e exportTaskLabel em scripts/gx-object-type-catalog.json quando montar lista a partir do índice ou do catálogo; a presença de -ObjectList classifica a rodada como exportação seletiva/cirúrgica para confronto de extras; após a exportação, seguir a secção Inventário do pacote após export seletivo (packageInventory no export.json + package-inventory.json); nunca reportar ao usuário a contagem de entradas da lista como contagem do pacote; quando exportar um único objeto, o formato Tipo:Nome continua válido sem separador-ParallelKbRoot / -IndexPath / -CatalogOverridePath — obrigatórios em export seletivo (-ObjectList sem -ExportAll/full): o wrapper consulta KbIntelligence antes do MSBuild (objectListPreflight no export.json, gateContext=export). Homônimo ou índice ausente/inválido → exit 35 (estágio pre-export-identity). Objeto ausente no índice mas possivelmente só na KB nativa → aviso e segue MSBuild; inventário pós-export continua obrigatório. Em sessão na pasta paralela da KB, passar a raiz da sessão em -ParallelKbRoot.-DependencyType — em export seletivo/cirúrgico que deve conter somente a lista nominal, usar "None"; valores além de None e o default formal quando omitido permanecem pendentes de confirmação nesta base-ReferenceType — em export seletivo/cirúrgico que deve conter somente a lista nominal, usar "None"; valores além de None e o default formal quando omitido permanecem pendentes de confirmação nesta base-ExportKbInfo-ExportAllParâmetros específicos de importação:
-InputPath — nome canônico da entrada primária (aliases retrocompatíveis -XpzPath e -Path); aceita .xpz (formato compactado padrão GeneXus), .xml ou .import_file.xml (envelope GeneXus com raiz <ExportFile>) como insumo válido para preview e import real, desde que o envelope tenha sido validado por Test-GeneXusImportFileEnvelope.ps1 na mesma rodada; a extensão aceita não é restringida pelo nome do parâmetro-PreviewMode-UpdateFilePath-IncludeItems — recorte seletivo no formato Tipo:Nome (separador ;, , ou linha); classifica a rodada como import seletivo para objectListPreflight-ExcludeItems-ParallelKbRoot / -IndexPath / -CatalogOverridePath — obrigatórios quando -IncludeItems estiver preenchido: pré-validação no índice antes do MSBuild (objectListPreflight no import.json ou preview, gateContext=import, estágio pre-import-identity). Homônimo ou índice ausente/inválido → exit 35; not_in_index → aviso e segue; inventário do pacote (passo 6c) continua obrigatório antes de import real-AutomaticBackup-ImportType-ImportKbInformation — tri-state: omitido ou false significam não emitir o atributo na task Import (omissão do atributo faz a task aplicar seu próprio default, documentado como true em 10-base-operacional-msbuild-headless.md); apenas true emite o atributo e exige que a task carregada exponha a propriedade. Bloqueio por assinatura só ocorre quando o valor for true em instalação sem suporte; false é tratado como omissão tanto no preview quanto no import realTest-GeneXusImportFileEnvelope.ps1 valida estrutura do envelope; não substitui a verificação do conjunto de objetos que efetivamente seria aplicado à KB na importação.Get-GeneXusImportPackageObjectInventory.ps1 -InputPath <import_file.xml ou .xpz> como inventário determinístico preferido. Para confronto com lista esperada, use -DeclaredDeltaPath <arquivo> ou -DeclaredDeltaItems "<lista Tipo:Nome separada por ; ou linha>". Para bloquear automaticamente divergência, acrescente -FailOnDeltaMismatch.xpz-builder com manifesto explícito na conversa (objetos + intenção do lote):
<ExportFile> (por exemplo todos os <Object sob <Objects>, ou conteúdo equivalente dentro do .xpz).xpz-builder como mudança pedida, auxiliar necessária ou extra não pedida; se for extra não pedida num pacote que o utilizador descreveu como correção pontual ou cirúrgica → ABORT salvo confirmação explícita.PackagedModule:GeneXus ou ExternalObject:Camera com nome no catálogo scripts/gx-platform-objects.json, refletido em systemObjectsPresent) num pacote tratado como delta mínimo → ABORT salvo pedido explícito desse conteúdo.totalAttributes alto) sem Transaction na lista declarada (attributesTopLevelUnreconciled / warning attributes-top-level-em-export-cirurgico) → tratar como arrasto de base (risco de estrutura de banco), declarar ao usuário e ABORT salvo confirmação explícita antes de import/sync.PreviewMode quando o pacote veio de export MSBuild, reempacotamento manual ou qualquer fluxo em que o agente não controlou fecho do lote na conversa.-ObjectList / Objects) não garante, por si só, pacote com um único objeto nem equivalência “lista nominal = conteúdo do zip”. Para pacote cirúrgico nominal, use -DependencyType "None" -ReferenceType "None" como prevenção na origem; ainda assim, nunca tratar tudo o que veio no pacote como intencional sem inventário e confronto.Distinção obrigatória entre comportamento esperado da task GeneXus e rejeição explícita no log. Fonte numérica: scripts/msbuild-exit-codes.catalog.json (hoje exitCode 48 = Categoria B).
Categoria A — comportamento esperado / decisão do agente (pode manter exitCode=0 do wrapper):
DependencyType/ReferenceType, systemObjectsPresent, atributos top-level em export cirúrgica (attributesTopLevelUnreconciled)Categoria B — rejeição MSBuild/compilador (barragem estrutural no wrapper):
error : no stdout/stderr (exportErrors, importErrors, previewErrors, buildErrors, specifyErrors no top-level do JSON, conforme o wrapper)invalidTypesRejected não vazio (export)error : no stderr não classificadas como ruído conhecido GeneXus 18 (ex.: ruído estrutural context [anonymous] já filtrado nos wrappers de build)executionEvidence.msBuildExitCode=0 mas Categoria B estiver populada, o wrapper rebaixa para exitCode=48 (msBuildCategoryBBlocked=true); o artefato pode existir no disco apenas para inspeçãoexitCode=48 é bloqueio cego — autorização ampla de import não cobre Categoria B (análogo a extras da Categoria A)A frase «sinalizar sem rebaixar exitCode» aplica-se somente à Categoria A.
exitCode classificado pelo wrapper = 0, sem Categoria B, e arquivo existente), antes de declarar ao usuário que a exportação está concluída de forma limpa ou de seguir para materialização/import/sync.Invoke-GeneXusXpzExport.ps1 já chama o inventário e preenche packageInventory no export.json + package-inventory.json no diretório de artefatos. Quando o inventário automático falhar (inventoryDegraded=true), abrir o .xpz manualmente ou chamar Get-GeneXusImportPackageObjectInventory.ps1 -InputPath <xpz> antes de fechar a rodada.-ObjectList foi informado (e não houve -ExportAll/-FullExport), a rodada é exportação seletiva/cirúrgica — o confronto de extras usa somente objetos do bloco <Objects> cujo par Tipo:Nome (case-insensitive) não está na lista. Quando -ExportAll ou -FullExport, não há conceito de “extra” face à lista; packageInventory reporta apenas contagens reais.Tipo:Nome normalizado ausente de -ObjectList. Atributos top-level entram em totalAttributes e na lista completa, mas não entram na conta de extras da lista nominal.-ObjectList não inclui nenhuma Transaction e o pacote traz Attribute sob <Attributes>, o motor emite warning attributes-top-level-em-export-cirurgico e attributesTopLevelUnreconciled=true — sinal de arrasto de base (ex.: export só de WorkWith/Procedure que puxou atributos de TRN). Com Transaction na lista, atributos top-level são esperados (controle negativo: sem esse warning). Promove operationalSubState para extras não conciliados quando exportErrors estiver vazio.scripts/gx-platform-objects.json com kind packagedModule ou externalObject. No inventário, PackagedModule/Module (GUID c88fffcd-... ou 00000000-...-000006) e ExternalObject (GUID c163e562-...) presentes no pacote aparecem em systemObjectsPresent com name, kind e typeName do XML. Exemplo: PackagedModule:GeneXus, não apenas Module:GeneXus. Num pacote cirúrgico, qualquer entrada em systemObjectsPresent não pedida exige declaração explícita ao usuário antes de preview/import/sync — mesmo que o MSBuild tenha concluído com exitCode=0.-ObjectList enquanto o .xpz contém centenas de <Object>/<Attribute>. A contagem no relatório ao usuário vem de packageInventory (ou inventário manual equivalente), não da lista solicitada.extrasSample ou totalAttributes como se fossem o conteúdo real do pacote, omitir atributos top-level quando attributesTopLevelUnreconciled=true, ou ignorar package-inventory.json quando o motor já gravou nominalInventoryAt / packageInventoryPath / artifacts.PackageInventoryPath. Em export seletiva com extrasCount > 0 ou com attributesTopLevelUnreconciled=true, a comunicação ao usuário deve listar cada item por nome, separado por bloco (<Objects> e <Attributes>). O JSON resumido serve à máquina; não substitui a comunicação ao humano.Tipo:Nome (ou lista equivalente em -ObjectList / delta declarado) e aceitar como conclusão limpa um pacote cujo objeto efetivo não corresponde à identidade pedida, sem reclamação visível no log e sem Categoria B. Distinguir três situações:
error : ... is not a valid type, invalidTypesRejected populado): não é silencioso — o wrapper rebaixa para exitCode=48; artefato só para inspeção; declarar risco de a task GeneXus ter resolvido só por nome antes do rebaixamento.WorkWith:Nome, pacote WorkWithForWeb:Nome com o mesmo Nome): não é fallback GeneXus por nome inexistente; é equivalência documentada em exportTaskLabel / 10a-gx-export-task-labels.md. O inventário registra deltaComparison.aliasResolutions[] (regra exportTaskLabel); usar requestedItemsFound, aliasResolutionCount no packageInventory e o sidecar — não tratar requestedItemsMissing isolado como falha quando o alias estiver populado.exitCode=0, sem Categoria B, mas identidade canônica não demonstrada no pacote (homônimo entre tipos, nome errado que ainda “achou” outro objeto, tipo no pacote diferente do pedido sem alias documentado): ABORT operacional; listar pedido vs inventário; não materializar/importar/sync. O wrapper bloqueia homônimo e índice inválido/ausente antes do MSBuild em export seletivo (-ObjectList) e import/preview seletivo (-IncludeItems) — exit 35; not_in_index gera aviso e não bloqueia (objeto pode existir só na KB nativa). Depois do export/import, inventário obrigatório e confronto explícito.error : no stdout com sucesso aparente da task (Categoria B): a task Export pode emitir linhas error : (ex.: X is not a valid type) e ainda concluir com Export Sucesso e __EXPORTED_FILE__. O wrapper captura em exportErrors / invalidTypesRejected via Read-MsBuildImportSignals.ps1 -Stage export e rebaixa para exitCode=48 quando a lista não estiver vazia. Nunca tratar como conclusão limpa. Em seletiva com tipos rejeitados, declarar risco de resolução por nome (homonímia) e verificar exportTaskLabel em 10a-gx-export-task-labels.md.knownStdOutNoise aparece no top-level do export.json (espelhando stdoutSignals.knownStdOutNoise e msbuild.export.signals.json) — não basta inspecionar só stdoutSignals; caso típico: cssproperties-access-denied para acesso negado a CssProperties.json quando a task ainda conclui com sucesso aparente.exportação concluída e inventário consolidado — XPZ existe, inventário obtido, sem exportErrors, e (em seletiva) sem extras não conciliados nem itens pedidos ausentes nem módulos/ExternalObjects de plataforma não declarados nem attributesTopLevelUnreconciledexportação concluída, inventário com extras não conciliados — XPZ existe e inventário obtido, mas em export seletiva há extras, itens pedidos ausentes, systemObjectsPresent não vazio e/ou attributesTopLevelUnreconciled num pacote tratado como cirúrgico; declarar ao usuário antes de materializar/importar (somente quando exportErrors estiver vazio)exportação parcial com errors do MSBuild — artefato não confiável — XPZ existe, exportErrors e/ou invalidTypesRejected não vazios; wrapper com exitCode=48; reproduzir linhas ao usuário; prioridade sobre sub-estados de inventário “consolidado”; artefato só para inspeçãoexportação concluída sem inventário (degradado) — XPZ existe, mas inventoryDegraded=true; inspeção manual obrigatória antes de fecharexportação headless concluída e XPZ gerado (falha no pós-processamento do wrapper) quando postProcessingFailed=true e evidência primária do log/arquivo sustentarem o XPZ.xpz, substituir manualmente o nó de um <Object> pelo XML da pasta paralela, reempacotar e importar sem inventário completo e sem alinhamento ao manifesto / delta.ObjetosDaKbEmXml ou área de geração local), o caminho preferido para import headless é montar import_file.xml com motor estruturado compartilhado: Build-GeneXusImportFileEnvelope.ps1 para montagem direta a partir de XMLs de objeto e template válido, com -AcervoPath <ObjetosDaKbEmXml> obrigatório, coerência pré-gravação por lastUpdate e Object/@type por mesmo guid, e objetos modificados declarados por -ModifiedObjectNames ou -ModifiedObjectGuids, ou New-XpzImportPackage.ps1 para montagem segura por frente em ObjetosGeradosParaImportacaoNaKbNoGenexus usando kb-source-metadata.md ou -TemplatePackagePath apontando para XML/import_file.xml ou .xpz comparável (skill xpz-builder, metadados em kb-source-metadata.md quando aplicável). Build-GeneXusImportFileEnvelope.ps1 continua cobrindo coerência documental de lastUpdate e Object/@type conforme seu contrato atual, mas não cobre trim global forte nesta versão. O .py é motor interno do wrapper, não rota operacional equivalente. No wrapper New-XpzImportPackage.ps1 o gate de drift 9-FD executa sempre antes do empacotamento (fail-closed): -AcervoPath é opcional e, quando omitido, o acervo canônico <RepoRoot>/ObjetosDaKbEmXml é resolvido automaticamente; sem acervo resolvível o empacotamento é bloqueado, e o JSON reporta acervoResolvedBy (explicit ou convention). Isso bloqueia XMLs desatualizados, com Object/@type divergente por mesmo guid ou com remoção forte de trailing whitespace herdado contra baseline por GUID único na frente, em vez de fabricar .xpz por export só para servir de envelope; acervo ambíguo por GUID é diagnóstico informativo front-object-type-drift-ambiguous-acervo com candidateAcervoPaths, não escolha automática de tipo. Quando a evidência local indicar que o fluxo ativo de importação exige envelope completo no estilo exportação da IDE, use template comparável exportado pela IDE sem limitar essa regra a uma versão GeneXus específica.lastUpdate velholastUpdate menor ou igual ao do objeto vivo na KB é aceito pelo import sem erro (exitCode 0, sem error : no log), mas a KB não atualiza o objeto. O resultado parece sucesso e desperdiça um ciclo import + build inteiro até se descobrir que nada mudou. O GeneXus exige lastUpdate estritamente maior que o do objeto vivo para efetivar a atualização.New-XpzImportPackage.ps1 roda o gate de drift 9-FD sempre (fail-closed); Build-GeneXusImportFileEnvelope.ps1 roda coerência frente-vs-acervo sempre, com -AcervoPath obrigatório. Em ambos, lastUpdate velho ou igual ao acervo em objeto declarado modificado bloqueia antes da gravação do pacote; Object/@type divergente por mesmo guid também bloqueia e exige decisão humana, sem autocorreção por cópia/bump. Proteção mecânica parcial nesta versão: no fluxo New-XpzImportPackage.ps1, o 9-FD detecta remoção forte de trailing whitespace herdado contra baseline por GUID único; não detecta introdução de trailing whitespace novo e não é detector completo de whitespace, reindentação ou EOL. Build-GeneXusImportFileEnvelope.ps1 continua cobrindo coerência documental de lastUpdate e Object/@type conforme seu contrato atual, mas não cobre trim global forte nesta versão.ObjetosDaKbEmXml, retrato do último sync), não contra a KB viva. Se a KB avançou desde o último sync, um lastUpdate "mais novo que o acervo" ainda pode ser <= ao objeto vivo, e o footgun escapa mesmo com o gate verde. O gate cobre o caso comum (esquecer de bumpar); não substitui conferir contra a KB real quando há suspeita de acervo defasado. Para garantia contra a KB viva, ressincronizar o acervo (xpz-sync) antes de empacotar.KMW/Source/identidade de envelope por outro meio).C:\Program Files (x86) será tratada como somente leituraKbPathGeneXusDirMsBuildPathWorkingDirectoryLogPathGenexus.Tasks.targets
Se WorkingDirectory estiver em caminho seguro e ainda não existir, o probe pode auto-criar exatamente essa pasta.GeneXusDir e MsBuildPath por ordem explícita de precedência e fallback, registrando origem e descarte de candidatos quando aplicávelapto para prosseguir ou não apto para prosseguir
O diagnóstico deve incluir status, summary, resolvedPaths, checks, blockingReasons, warnings e strategyTrace.
O diagnóstico deve distinguir WorkingDirectory já existente de WorkingDirectory auto-criado no caminho explícito e seguro.
Preferir JSON como formato canônico inicial.
6b. Quando o objetivo for importação (preview ou real), executar o gate de validação do envelope antes de qualquer chamada ao MSBuild:
Test-GeneXusImportFileEnvelope.ps1 -InputPath <caminho>; a saída de máquina é JSON por padrão. Para Panel com molde/pacote comparável disponível, passar também -PanelReferencePath <molde-ou-pacote> para confirmar o par level id/layout idnão apto para prosseguir → ABORT; apresentar blockingReasons ao usuário antes de prosseguir; não chamar MSBuildapto com ressalvas → apresentar warnings; exigir confirmação explícita do usuário antes de prosseguir para preview ou import realapto para prosseguir → prosseguir normalmenteGet-GeneXusImportPackageObjectInventory.ps1 -InputPath <pacote import_file.xml ou .xpz>; a saída de máquina é JSON por padrão. Se houver delta declarado em arquivo Tipo:Nome, passar -DeclaredDeltaPath ou -DeclaredDeltaItems; quando a rodada exigir bloqueio automático, -FailOnDeltaMismatch. Se o pacote contiver extras não conciliados, módulo/ExternalObject de plataforma não pedido ou attributesTopLevelUnreconciled num pacote cirúrgico, ABORT salvo confirmação explícita do utilizador. Omitir este passo apenas quando o pacote foi gerado na mesma rodada pelo fluxo xpz-builder com manifesto na conversa que já feche o lote esperado.Quando o usuário já autorizou importação real headless na mesma sessão (ex.: «pode importar», «gerar e importar», ou «sim»/«pode executar» a uma proposta explícita do agente que inclua import real) e o ambiente for controlado:
Test-GeneXusImportFileEnvelope.ps1 → apto para prosseguir e inventário do pacote (passo 6c) sem bloqueio, executar Invoke-GeneXusXpzImport.ps1 na mesma rodada. apto para prosseguir valida estrutura do envelope, não substitui o inventário nem autoriza ignorar extras.Test-GeneXusXpzImportPreview.ps1 antes do import real neste cenário. Preview permanece para rodadas exploratórias ou quando import real ainda não foi autorizado.KbPath, VersionName, EnvironmentName, WorkingDirectory e LogPath (passos 7–8) se ainda faltarem.-StartWatcher e -MonitorLogPath (ausência de -MonitorLogPath bloqueia cedo, exit 46). Não tratar watcher como opcional nesta skill.apto com ressalvas no envelope, bloqueio de assinatura da task, falha de permissão ou limite do ambiente → parar e reportar; não substituir por import na IDE sem declarar.
7b. Categoria B no export/preview: se a exportação que alimentou o pacote saiu com exitCode=48, exportErrors ou invalidTypesRejected, ABORT antes do import real — autorização de import na sessão não cobre rejeição MSBuild no log.xpz-msbuild-build nem reorg ampla; build só após proposta explícita aceita pelo usuário.Anti-padrão (nomeado): parada após envelope apto — envelope apto para prosseguir, usuário já autorizou import real, inventário sem bloqueio, e o agente não chama Invoke-GeneXusXpzImport.ps1.
Anti-padrão (nomeado): reempacotar lixo de export — receber .xpz/export com objetos além do delta, incluir esses itens no import_file.xml da frente atual sem classificar e sem confirmação, e tratar o pacote como cirúrgico.
Invocação canônica (ajustar caminhos):
pwsh -NoProfile -File scripts/Invoke-GeneXusXpzImport.ps1 `
-KbPath "<caminho-kb>" `
-InputPath "<caminho.import_file.xml ou .xpz>" `
-VersionName "<versao>" `
-EnvironmentName "<ambiente>" `
-WorkingDirectory "<pasta-msbuild-segura>" `
-LogPath "<pasta-artefatos>/import/import.log" `
-MonitorLogPath "<pasta-artefatos>/import/watcher.log" `
-StartWatcher
Environment ativo quando aplicável