xpz-msbuild-import-export

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

xpz-msbuild-import-export

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:

• o que conta como prontidão operacional estável
• quais limites conhecidos ainda exigem uso controlado
• como classificar exceções sem confundi-las com defeito central do wrapper

Exceções já mapeadas que a skill deve tratar explicitamente:

• conteúdo inconsistente da KB/XPZ, como KB_Teste_A
• validação funcional incompleta por GeneXus Server ou licença, como KB_Teste_E
• execução longa em KB grande, como KB_Teste_Grande_A
• warning estrutural por extensão ausente, como WebPanelDesigner/K2B Object Designer

Critério atual de prontidão operacional desta skill:

• probe (sondagem técnica inicial), abertura headless, exportação, PreviewMode e importação real já validados em KBs de teste controladas
• classificação explícita entre sucesso operacional, validação funcional incompleta e problema de conteúdo da KB/XPZ
• logs, artefatos e parâmetros sensíveis rastreáveis
• limites conhecidos já documentados e não tratados como surpresa operacional

Uso mais amplo desta skill ainda depende de:

• critério estável para KBs com dependência externa, licença ou extensão ausente
• interpretação madura de execução longa em KB grande
• confiança suficiente para uso fora de ambiente de experimento controlado

---

GUIDELINE

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): o PreviewMode prioriza inspeção, mas não valida uma API — reporta importTaskSuccess:true mesmo para API inválida (valor de [SecurityLevel] inválido, Procedure de implementação ausente). Só a importação real roda a validação de gramática/referências da API (inclusive a resolução API => Procedure). Quando o objetivo for validar uma API from-spec, usar importação real (empacotando a API com seu Procedure, ou fazendo staging do Procedure antes) — a autorização de import real e os gates de envelope continuam valendo. Ver 10-base-operacional-msbuild-headless.md e xpz-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.

PATH RESOLUTION

• Este SKILL.md fica em uma subpasta de skill sob a raiz do repositório.
• Resolva referências ../arquivo.md relativas à pasta desta skill, não ao diretório corrente.
• Se a skill estiver publicada por symlink, junction ou outro reparse point, resolva primeiro a pasta real da skill e só então interprete referências relativas como ../arquivo.md.
• Na prática, ../ aponta para a base metodológica compartilhada da raiz.

---

TRIGGERS

Use esta skill para:

• planejar ou executar validação de ambiente para GeneXus via MSBuild
• abrir a Knowledge Base por OpenKnowledgeBase
• confirmar versão ativa e Environment ativo
• executar preview de importação com PreviewMode
• gerar UpdateFile, quando suportado pela task carregada, para análise prévia de impacto
• exportar XPZ com parâmetros explícitos
• importar XPZ apenas em fase explicitamente autorizada de teste controlado
• classificar resultado em sucesso operacional versus confirmação funcional pendente
• inspecionar propriedades da KB, Version, Environment, Generator, DataStore ou Object para diagnóstico pré-operação via Get*Property

Do NOT use esta skill para:

• substituir o fluxo oficial atual da trilha paralela da KB
• cenários que dependam de GeneXus Server como requisito operacional
• KB de produção ou homologação compartilhada sem janela clara para experimento
• inferir silenciosamente KbPath, versão, Environment ou parâmetros sensíveis
• afirmar sucesso funcional apenas porque a chamada via MSBuild terminou sem erro
• editar ou ajustar o Source, Rules ou CDATA de um objeto de KB — isso pertence ao xpz-builder

---

RESPONSIBILITIES

• Usar 10-base-operacional-msbuild-headless como base principal desta frente
• Validar explicitamente KbPath, GeneXusDir, MsBuildPath, WorkingDirectory, LogPath e Genexus.Tasks.targets
• Enriquecer preventivamente o $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 puro
• Tratar Test-GeneXusMsBuildSetup.ps1 como probe (sondagem técnica inicial) não invasivo, anterior a qualquer abertura de KB
• Tratar C:\Program Files (x86) como estritamente somente leitura
• Garantir que logs, temporários, .msbuild e artefatos sejam gerados fora de C:\Program Files (x86)
• Permitir auto-criação apenas do WorkingDirectory explicitamente informado, depois de validado como seguro e fora das áreas proibidas
• Preferir Temp como destino de artefatos efêmeros de execução e manter scripts como pasta de wrappers permanentes
• Distinguir claramente:
  • sucesso operacional da chamada
  • efeito funcional observado depois no GeneXus
• Classificar explicitamente quando a rodada for ensaio 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 posterior
• Em ensaio metodológico/experimental, não narrar o resultado como mudança funcional validada; limitar a conclusão ao que a evidência realmente cobriu
• Quando a estratégia segura exigir mais de uma fase, tratar cada rodada como incremento controlado e validar build/import antes da fase seguinte
• Sucesso operacional de uma fase não autoriza recompor automaticamente pacote acumulado para a fase seguinte; a próxima rodada deve preferir o delta novo ainda não validado
• Exigir que o probe (sondagem técnica inicial) devolva diagnóstico estruturado com status, summary, resolvedPaths, checks, blockingReasons, warnings e strategyTrace
• Preferir JSON como formato canônico inicial desse diagnóstico
• Registrar stdoutSignals (campos semânticos por domínio), stderrContent, stderrFilteredNoise, exitCode, caminho do .msbuild temporário e caminho do log
• Validar a assinatura efetiva do wrapper e da task antes de assumir formato de parâmetro sensível de exportação ou importação
• Em exportação full da KB, preferir o atalho ergonômico -FullExport do wrapper local quando ele existir; manter ExportAll='true' apenas como compatibilidade com contratos antigos
• Privilegiar PreviewMode 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)
• Distinguir explicitamente operação na KB de atualização do acervo oficial
• Sucesso de preview ou importação não autoriza atualização manual de ObjetosDaKbEmXml
• Quando houver retorno oficial da KB em XPZ, a atualização de ObjetosDaKbEmXml deve ocorrer depois, pelo fluxo de xpz-sync
• Tratar ImportKBInformation, UpdateFile e defaults internos de importação/exportação como sensíveis e dependentes da assinatura efetiva da task Import
• Tratar ImportKbInformation 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.
• Não tratar bloqueio por assinatura da task como ajuste silencioso: quando preview ou import bloquear porque a task carregada não expõe propriedade sensível passada pelo agente ou pelo wrapper, é proibido repetir a chamada sem o parâmetro sem antes declarar nominalmente (1) qual propriedade ausente, (2) que o pacote não foi testado ou importado naquela rodada, (3) que a incompatibilidade é divergência de contrato operacional entre chamada/wrapper e assinatura efetiva da instalação, e (4) qual correção será aplicada — omitir parâmetro neutro, corrigir wrapper para omitir automaticamente quando não suportado, ou abortar a frente. Só depois dessa declaração explícita é admissível repetir a chamada com o parâmetro omitido, e nesse caso classificar a rodada como chamada corrigida por parâmetro sensível omitido.
• Normalizar recortes múltiplos de IncludeItems e ExcludeItems como lista antes de serializar para a task carregada
• Preservar importedItems como lista em qualquer diagnóstico JSON, mesmo quando houver apenas um item
• Declarar importaçã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ído
• Quando o Invoke-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 import
• Quando a task carregada não expuser UpdateFile 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 bloqueio
• Tratar Get*Property como operação de leitura segura, sem efeito sobre a KB
• Não usar o valor retornado por GetVersionProperty -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 GetActiveVersion
• Não usar o valor retornado por GetEnvironmentProperty -Name Name como -EnvironmentName pelo mesmo motivo; usar GetActiveEnvironment para obter o identificador ativo compatível
• Quando SetActiveVersion 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.
• Validar -Level e -Name explicitamente antes de emitir a task; exigir -Target quando -Level for Generator, DataStore ou Object
• Nunca inferir o nome da propriedade; sempre exigir -Name explícito
• Quando recortes sucessivos isolarem erro residual de Source, 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 wrapper
• Quando o sintoma envolver código de evento GeneXus que parece não executar ou não surtir efeito, distinguir antes de editar o source os dois mecanismos documentados em 02-regras-operacionais-e-runtime.md, seção Mecanismos 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.
• Mecanismo (a): se 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).
• Mecanismo (b): se import OK (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.
• Quando um teste controlado com 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
• Exigir confirmação explícita antes de importação real
• Recomendar reabertura da KB na IDE oficial após testes relevantes para observar warning, marca de versão ou outro efeito colateral
• Perguntas sobre conteúdo nominal de um XPZ — tanto em turnos posteriores da mesma rodada quanto em sessões novas sobre um .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)
• Export legado GeneXus 9 (perfil automático do inventário): se o .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)

---

COMMUNICATION

• 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:

  • objetivo metodológico da rodada
  • resultado operacional observado
  • confirmação funcional ainda não coberta

• 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

---

STRUCTURE

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

---

EXPECTED INTERFACE

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 invasivo
• Open-GeneXusKbHeadless.ps1: implementado para abertura e fechamento controlados da KB, com contexto ativo e sem import/export
• Test-GeneXusXpzImportPreview.ps1: implementado para PreviewMode de importação e já validado nesta conversa com XPZ real
• Invoke-GeneXusXpzExport.ps1: implementado para exportação headless de XPZ com parâmetros explícitos e diagnóstico JSON
• Invoke-GeneXusXpzImport.ps1: implementado para importação real de XPZ com parâmetros explícitos e diagnóstico JSON
• Invoke-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 Panel
• Test-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.md
• Extract-XpzObject.ps1: implementado para extrair um objeto específico de XML/XPZ ou retornar resumo JSON sem imprimir o pacote inteiro
• Get-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 CDATA
• Compare-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/event
• Test-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 KB
• Get-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 real
• GeneXusMsBuildWatcherSupport.ps1: implementado como helper comum do contrato de watcher dos wrappers MSBuild; centraliza -StartWatcher, -MonitorLogPath, watcherContext, timing.phases e leitura do log do monitor
• Watch-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 recomendado
• Resolve-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 Java

Scripts nesta frente:

• Test-GeneXusMsBuildSetup.ps1
  • status atual: implementado como probe (sondagem técnica inicial) não invasivo
  • descoberta de MsBuildPath quando omitido: vswhere.exe e catálogo estático em scripts/GeneXusMsBuildPathContract.ps1; JSON inclui msBuildProbe (resolutionSource, vsWhere, candidates[])
• Test-GeneXusMsBuildDiscoveryContract.ps1
  • status atual: implementado; regressão mínima do catálogo de candidatos MSBuild (não substitui probe real com GeneXus/VS instalados)
• Open-GeneXusKbHeadless.ps1
  • status atual: implementado para abertura e fechamento controlados da KB
  • saída esperada: status, summary, exitCode, executionEvidence, stage, requestedContext, observedContext, artifacts, stderrContent, blockingReasons, warnings, strategyTrace, msBuildExitCode top-level como compatibilidade transitória quando existir, e caminhos dos logs
• Test-GeneXusXpzImportPreview.ps1
  • status atual: implementado para PreviewMode sem importação real, com IncludeItems e ExcludeItems validados nesta instalação
  • contrato de resiliência do pós-processamento: o bloco que faz parse do stdout, monta 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 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 concluiu
  • contrato de sinais compactos: após o MSBuild, o wrapper deve gravar msbuild.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ão
• Invoke-GeneXusXpzExport.ps1
  • status atual: implementado para exportação headless de XPZ com parâmetros explícitos e validação da task carregada
  • contrato de resiliência do pós-processamento: o bloco que faz parse do stdout, lê __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 concluiu
• Invoke-GeneXusXpzImport.ps1
  • status atual: implementado para importação real de XPZ com parâmetros explícitos e diagnóstico JSON
  • contrato de resiliência do pós-processamento: o bloco que faz parse do stdout, monta 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 concluiu
  • contrato de sinais compactos: após o MSBuild, o wrapper deve gravar msbuild.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óstico
• Invoke-GeneXusXpzImportThenBuild.ps1
  • status atual: implementado para encadear import real e BuildAll pós-import com parada condicional
  • saída esperada: JSON único com status/roundtripStatus, summary, exitCode, importJson, buildJson, importReadyForBuild, buildSkippedReason, importProcess, buildProcess, resolvedPaths, artifacts, blockingReasons, warnings e strategyTrace
  • regra de segurança: se Invoke-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 buildSkippedReason
  • resultado do BuildAll: roundtripStatus é 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.
  • gates de build propagados: -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
  • flags de validação de deploy bin propagadas: -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-build
• Read-MsBuildImportSignals.ps1
  • status atual: implementado
  • objetivo: ler logs brutos de preview/import sem despejar CDATA ou stdout inteiro na conversa
  • parâmetros: -Path (diretório de artefatos ou stdout), -StdOutPath, -StdErrPath, -ExpectedItems, -Stage, -OutputPath, -AsJson
  • saída esperada: importedItems, expectedItemsRaw/importedItemsRaw, expectedItemsCanonical/importedItemsCanonical, itemAliasMatches, warnings, errors, knownStdOutNoise, gxImportLogReadStatus/gxImportLogReadError, diagnosticDegraded, activeVersion, activeEnvironment, importTaskSuccess, layoutWarnings agrupados por Panel e contadores compactos
  • knownStdOutNoise 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
  • status atual: implementado
  • objetivo: validar extração/classificação de Read-MsBuildImportSignals.ps1 sem abrir KB
  • uso típico: regressão local após mudança no leitor compacto ou nos wrappers de preview/import
• Extract-XpzObject.ps1, Get-GeneXusObjectSummary.ps1, Compare-GeneXusPanelShape.ps1
  • status atual: implementados
  • objetivo: evitar despejo de XML/XPZ ou CDATA gigante durante triagem de pacote, diagnóstico de Panel e comparação de shape
  • uso típico: extrair um único objeto por nome/tipo, resumir Part/identidade/shape e comparar Panels exportados pela IDE contra Panels gerados localmente
• Test-GeneXusKbConsistency.ps1
  • status atual: implementado; classifica KB consistente, inconsistências detectadas, check parcial por timeout da Etapa 3 e KB inacessível; Fix="true" exige confirmação interativa
• Test-GeneXusImportFileEnvelope.ps1
  • status atual: implementado
  • runtime: executar em pwsh 7.4 ou superior; o script declara #requires -Version 7.4 e Windows PowerShell 5.1 não é runtime suportado
  • objetivo: validação estrutural estática do import_file.xml antes de qualquer chamada ao MSBuild; não invasivo, não abre KB, não requer GeneXus instalado
  • parâmetros obrigatórios: -InputPath (caminho do import_file.xml)
  • parâmetros opcionais: -PanelReferencePath (objeto ou pacote XML/XPZ comparável usado para confirmar par level id/layout id em Panel)
  • saída esperada: status (apto para prosseguir | apto com ressalvas | não apto para prosseguir), checks (mapa de verificações individuais), objectCount, blockingReasons, warnings, information
  • verificações realizadas: XML bem-formado; raiz <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
  • regra Panel: sem -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-suspicious
  • regra cross-KB: formato GUID valido não basta para import headless; quando houver KB nativa local esperada, Source/@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
  • status atual: implementado para import_file.xml, XML com raiz <ExportFile> ou .xpz (XML interno único)
  • objetivo: inventariar o conteúdo efetivo do pacote antes de preview/import, separando Objects, Attributes top-level, tipos mapeados, GUIDs e confronto opcional com delta declarado
  • parâmetros obrigatórios: -InputPath (import_file.xml, XML equivalente ou .xpz)
  • parâmetros opcionais: -DeclaredDeltaPath, -DeclaredDeltaItems, -FailOnDeltaMismatch, -CatalogPath, -SystemModulesCatalogPath, -SystemExternalObjectsCatalogPath
  • quando o pacote cotidiano já é import_file.xml, não fabricar .xpz só para validar — chamar o motor direto sobre o import_file.xml
• Watch-GeneXusMsBuildLog.ps1
  • status atual: implementado
  • objetivo: monitorar incrementalmente o log de uma execução headless em andamento; encerra sozinho quando o processo termina; usar especialmente em importações de KB grande onde o invocador pode encerrar por timeout antes do MSBuild concluir
  • parâmetros obrigatórios: -Pid, -LogPath
  • parâmetros opcionais: -MonitorLog, -IntervalSeconds (default 5), -SilenceThresholdSeconds (default 120)
• GeneXusMsBuildWatcherSupport.ps1
  • status atual: implementado
  • objetivo: helper comum para os wrappers MSBuild dispararem o watcher e registrarem watcherContext/timing.phases com o mesmo contrato
• GeneXusMsBuildStderrNoiseSupport.ps1
  • status atual: implementado
  • objetivo: helper comum para filtrar somente os ruídos estruturais conhecidos do GeneXus 18 nos diagnósticos stderrFilteredNoise, preservando erros reais em stderrContent; consumido por import/export/preview e demais wrappers headless desta skill
• Test-GeneXusRuntimeFreshness.ps1
  • status atual: implementado
  • objetivo: diagnosticar se o runtime GeneXus reflete a versão mais recente de um objeto após import+build; somente leitura, não abre KB, não invoca MSBuild
  • parâmetros obrigatórios: -KbPath, -ObjectName, -ImportedAt
  • parâmetros opcionais: -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), -AsJson
  • saída esperada: runtime-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
  • status atual: implementado
  • objetivo: leitura de propriedade em qualquer nível da KB sem alterar nenhum dado
  • parâmetros obrigatórios: -KbPath, -Level (KB | Version | Environment | Generator | DataStore | Object), -Name, -WorkingDirectory, -LogPath
  • parâmetros opcionais: -Target (obrigatório quando -Level for Generator, DataStore ou Object; nome do generator, datastore ou objeto), -GeneXusDir, -MsBuildPath, -VersionName, -EnvironmentName, -VerboseLog
  • saída esperada: status (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 log
  • tasks confirmadas no assembly: GetKnowledgeBaseProperty, 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 comum
  • incompatibilidade conhecida e verificada empiricamente: GetVersionProperty -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 GetActiveEnvironment

Contrato inicial específico de Test-GeneXusMsBuildSetup.ps1:

• obrigatórios: -WorkingDirectory, -LogPath
• opcionais: -GeneXusDir, -MsBuildPath, -KbPath, -VerboseLog
• regra de contrato: -WorkingDirectory continua explícito; quando o caminho seguro ainda não existir, o probe pode criar exatamente essa pasta e registrar isso no diagnóstico
• descoberta de MsBuildPath 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.md
• saída JSON do probe inclui msBuildProbe (resolutionSource, vsWhere, candidates[] com path/source/exists/selected) além de strategyTrace
• regressão mínima do catálogo (sem substituir probe real): scripts/Test-GeneXusMsBuildDiscoveryContract.ps1
• códigos de saída contratuais:
  • 0 para apto para prosseguir
  • 10 a 16 para bloqueios operacionais esperados com diagnóstico estruturado
  • 90 para falha interna do script antes de diagnóstico completo

Parâ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
• -ExportAll

Parâ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 real

---

INVENTÁRIO DO PACOTE ANTES DO IMPORT REAL

• O gate Test-GeneXusImportFileEnvelope.ps1 valida estrutura do envelope; não substitui a verificação do conjunto de objetos que efetivamente seria aplicado à KB na importação.
• Use 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.
• Checklist obrigatório antes de importação real quando o pacote não foi montado na mesma rodada pelo fluxo xpz-builder com manifesto explícito na conversa (objetos + intenção do lote):
  • Extrair a lista completa de objetos no <ExportFile> (por exemplo todos os <Object sob <Objects>, ou conteúdo equivalente dentro do .xpz).
  • Confrontar com o delta declarado / pedido do utilizador (tipo e nome de cada objeto em foco). Cada objeto extra deve ser classificado no espírito de 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.
  • Se aparecer objeto de plataforma/SDK GeneXus (por exemplo 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.
  • Se em export seletiva houver muitos atributos top-level (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.
• Recomendado executar o mesmo inventário antes de 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.
• Exportação com lista explícita (-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.

---

Categorias A e B (MSBuild headless)

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):

• extras por DependencyType/ReferenceType, systemObjectsPresent, atributos top-level em export cirúrgica (attributesTopLevelUnreconciled)
• tratamento operacional: inventário, declaração ao usuário, Decisão pós-gates com ABORT antes de import real quando houver extra não previsto — autorização de import na sessão não cobre esses casos

Categoria B — rejeição MSBuild/compilador (barragem estrutural no wrapper):

• linhas error : no stdout/stderr (exportErrors, importErrors, previewErrors, buildErrors, specifyErrors no top-level do JSON, conforme o wrapper)
• invalidTypesRejected não vazio (export)
• mensagens error : no stderr não classificadas como ruído conhecido GeneXus 18 (ex.: ruído estrutural context [anonymous] já filtrado nos wrappers de build)
• quando 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ção
• o agente nunca declara export/import/preview/build como entrega operacional limpa nesse cenário; PARAR e pedir decisão explícita do usuário antes de materializar, importar, sync ou push
• na Decisão pós-gates, exitCode=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.

---

INVENTÁRIO DO PACOTE APÓS EXPORT SELETIVO

• Aplicar sempre que a exportação headless concluir com XPZ gerado (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.
• Motor preferido: 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.
• Classificação da rodada: quando -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.
• Critério de extra (seletiva): objeto presente no pacote com 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.
• Atributos top-level em export cirúrgica: quando -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.
• Objetos de plataforma/SDK: entradas em 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.
• Anti-padrão (nomeado): contagem da lista no lugar do pacote — relatar “28 objetos exportados” contando entradas de -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.
• Anti-padrão (nomeado): amostra de extras no lugar da lista completa — relatar 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.
• Anti-padrão (nomeado): fallback silencioso por nome — pedir 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:
  • Tipo rejeitado no log (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.
  • Divergência de rótulo Export vs catálogo (ex.: lista 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.
  • Silêncio real — tipo aceito pela task, 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.
• Erros 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.
• Ruído conhecido no stdout (export): 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.
• Sub-estados de export (operacionais, após inventário e sinais de stdout):
  • 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 attributesTopLevelUnreconciled
  • exportaçã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ção
  • exportação concluída sem inventário (degradado) — XPZ existe, mas inventoryDegraded=true; inspeção manual obrigatória antes de fechar
  • Manter também exportaçã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

Anti-padrão (nomeado): export MSBuild como “casca” + patch + import

• Evitar: exportar da KB só para obter um .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.
• Quando o XML autoritativo já está na pasta paralela (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.

Footgun (nomeado): import inócuo por lastUpdate velho

• Sintoma: um pacote cujo objeto tem lastUpdate 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.
• Proteção upstream: o empacotamento por 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.
• Limite honesto da proteção: os dois gates comparam contra o acervo (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.

Exportação headless e alinhamento ao pedido

• Não iniciar exportação headless da KB como passo próprio quando o utilizador pediu apenas importar alterações já existentes na pasta paralela, salvo pedido explícito de exportação ou confirmação explícita de que a exportação é indispensável (por exemplo impossibilidade documentada de obter KMW/Source/identidade de envelope por outro meio).

---

WORKFLOW (fluxo de trabalho)

1. Reler a documentação local aplicável e usar 10-base-operacional-msbuild-headless como referência principal
2. Validar se o cenário é compatível com uso controlado e ambiente controlado
3. Confirmar que C:\Program Files (x86) será tratada como somente leitura
4. Executar primeiro um probe (sondagem técnica inicial) não invasivo para validar:
   • KbPath
   • GeneXusDir
   • MsBuildPath
   • WorkingDirectory
   • LogPath
   • existência de Genexus.Tasks.targets Se WorkingDirectory estiver em caminho seguro e ainda não existir, o probe pode auto-criar exatamente essa pasta.
5. Resolver GeneXusDir e MsBuildPath por ordem explícita de precedência e fallback, registrando origem e descarte de candidatos quando aplicável
6. Classificar o resultado do probe (sondagem técnica inicial) como apto 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:
   • Chamar 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 id
   • Interpretar o resultado:
     • não apto para prosseguir → ABORT; apresentar blockingReasons ao usuário antes de prosseguir; não chamar MSBuild
     • apto com ressalvas → apresentar warnings; exigir confirmação explícita do usuário antes de prosseguir para preview ou import real
     • apto para prosseguir → prosseguir normalmente
   • Este gate é não invasivo: lê apenas o arquivo local, não abre KB, não requer GeneXus instalado
   • Aplicar mesmo quando o arquivo vier de geração anterior já validada — o gate é obrigatório por rodada, não por sessão 6c. Antes de importação real: executar o inventário do pacote (lista completa de objetos no envelope) e confrontá-lo com o delta declarado, conforme a secção Inventário do pacote antes do import real. Preferir Get-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.

Decisão pós-gates (importação real autorizada na sessão)

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:

1. Envelope + inventário: com 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.
2. Sem nova confirmação de import: o passo 6b é obrigatório por rodada, não uma nova autorização humana por rodada. Não encerrar a sessão só porque o envelope está apto.
3. Preview dispensável: não exigir 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.
4. Pré-requisitos MSBuild: resolver KbPath, VersionName, EnvironmentName, WorkingDirectory e LogPath (passos 7–8) se ainda faltarem.
5. Watcher obrigatório: import real com -StartWatcher e -MonitorLogPath (ausência de -MonitorLogPath bloqueia cedo, exit 46). Não tratar watcher como opcional nesta skill.
6. Parada obrigatória (extras): se o inventário ou a conciliação com o delta revelar objeto extra não previsto — objeto, atributo top-level, módulo de plataforma ou ExternalObject fora do pedido da rodada, inclusive itens herdados de export/reempacotamento sem classificação — ABORT imediato antes de qualquer import real; apresentar lista completa do que está no pacote, origem provável (export gordo, merge na montagem, dependência não justificada) e aguardar decisão explícita do usuário. Autorização de import na sessão não cobre importar extras: impacto pode incluir builds longos (ex.: módulos de plataforma). Ver também anti-padrão reempacotar lixo de export.
7. Ressalvas: 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.
8. Build separado: autorização de import não autoriza 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

7. Só depois abrir a KB e confirmar versão ativa e Environment ativo quando aplicável