Menu
Executa sincronização ou conferência de XPZ de uma KB GeneXus chamando os scripts locais do repositório ativo
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle 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
Skill para importação e exportação de XPZ via MSBuild, com execução sem interface gráfica, parâmetros explícitos, rastreabilidade e gates (pontos de liberação ou bloqueio) de segurança
Permite ao agente principal delegar tarefas menores, pedir segunda opinião ou conduzir revisão por pares/peer review de plano/design por painel multi-modelo via opencode, Codex, Claude Code (Opus 4.8), GitHub Copilot CLI ou Gemini CLI; ao receber "revisão por pares", carregar esta skill, perguntar revisores preferidos se não houver preferred-reviewers.json, não presumir assinatura externa e nunca rotular parecer solo como revisão por pares; acionamento sempre humano
Skill para validação de build pós-import via MSBuild, com execução sem interface gráfica, parâmetros explícitos, classificação de resultado e gates de segurança contra reorg não autorizada
| name | xpz-sync |
| description | Executa sincronização ou conferência de XPZ de uma KB GeneXus chamando os scripts locais do repositório ativo |
Invoca os scripts locais do repositório GeneXus ativo para sincronizar XMLs individuais a partir de um XPZ exportado pela IDE, ou para conferir um export completo da KB.
Identificar a raiz do repositório pelo contexto, localizar os scripts de sincronização na pasta scripts\, montar o comando correto e executá-lo via Bash. Reportar o resultado de forma clara. Não alterar arquivos manualmente — delegar tudo ao script. Tratar ObjetosDaKbEmXml como snapshot oficial somente leitura para agentes e não antecipar manualmente nenhuma promoção para esse acervo. Distinguir sempre a pasta nativa da KB da pasta paralela da KB. Se houver edição detectada ou pretendida em ObjetosDaKbEmXml para delta ainda não reexportado oficialmente pela KB, tratar isso como erro explícito de processo.
ObjetosDaKbEmXml é o snapshot oficial da KB e nunca deve ser alterado manualmente pelo agente.ObjetosDaKbEmXml só pode ser atualizado pelo fluxo oficial de sync, a partir de XPZ exportado pela IDE do GeneXus.ObjetosDaKbEmXml.XPZ oficial da KB, o trabalho deve permanecer em ObjetosGeradosParaImportacaoNaKbNoGenexus.Quando o mesmo XPZ for reprocessado após atualização do arquivo exportado, tratar o novo resultado como um novo snapshot daquele insumo, não como repetição irrelevante do processamento anterior. A classificação updated versus unchanged pertence ao resultado daquele processamento específico.
Os nomes das pastas são apenas padrões sugeridos quando o usuário não informar outros. O que manda é a função da pasta no fluxo.
Quando a base compartilhada ganhar um parâmetro operacional relevante, isso significa apenas que a capacidade existe no motor compartilhado. A exposição em wrappers locais continua sendo decisão local e pode estar defasada. Nesses casos, o agente deve reconhecer a defasagem como oportunidade de adaptação local, propor a mudança ao usuário e aguardar aprovação explícita; não deve alterar wrappers locais por conta própria.
A superfície do wrapper local também pode ficar temporariamente à frente, atrás ou levemente desalinhada em relação ao motor compartilhado efetivo daquela pasta paralela da KB. Quando a falha atingir apenas um parâmetro opcional de conferência/comparação e o sync principal continuar viável, tratar o caso como divergência wrapper/engine: rerodar sem o opcional, registrar o incidente no relato e não classificar isso automaticamente como bloqueio da operação principal.
Os .example.ps1 da base metodológica podem servir como referência para
consertar ou reconstruir wrappers locais finais, mas não substituem o wrapper
local real e não devem ser usados como fallback automático de execução no fluxo
normal da pasta paralela da KB.
Se a pasta paralela da KB ainda não estiver montada, validada ou mapeada, parar e usar xpz-kb-parallel-setup antes do sync.
SKILL.md fica dentro de uma subpasta de skill sob a raiz do repositório.../arquivo.md deve ser resolvida a partir da pasta deste SKILL.md, e não do diretório de trabalho corrente.../ aponta para a base metodológica compartilhada na pasta-pai desta skill.Use esta skill para:
.xpz exportado da IDEDo NOT use this skill para:
xpz-builder)xpz-reader)xpz-daemon)xpz-index-triage quando houver índice KbIntelligence disponível)xpz-kb-parallel-setup)O repositório deve conter em <repo_root>\scripts\ dois wrappers:
| Propósito | Quando usar |
|---|---|
| Atualização diária — extrai e materializa XMLs no acervo a partir de um XPZ parcial | XPZ do dia a dia exportado pela IDE |
| Conferência full — verifica completude do acervo contra um export completo da KB, sem regravar nada | Novo export full da KB |
Os nomes exatos dos wrappers são definidos por cada repositório. Consulte o README.md local para identificá-los.
Quando o usuário não informar nomes alternativos, adotar estas subpastas na raiz da KB:
ObjetosDaKbEmXml: acervo oficial somente leitura para agentes (editar o acervo esperando que o pacote use essa versão é anti-padrão; ver 02-regras-operacionais-e-runtime.md, anti-padrão "editar acervo esperando que o pacote pegue")XpzExportadosPelaIDE: entrada dos .xpz exportados pela IDEscripts: wrappers .ps1 que tratam XPZTemp: destino de artefatos efêmeros de execução, como diretórios temporários de wrappers, logs auxiliares e saídas intermediáriasKbIntelligence: pasta do índice SQLite derivado e regenerável, quando esse fluxo estiver adotado na KBObjetosGeradosParaImportacaoNaKbNoGenexus: saída de XMLs temporários para importação manual, organizada por frente em subpastas NomeCurto_GUID_YYYYMMDD; essa subpasta é a unidade ativa da frentePacotesGeradosParaImportacaoNaKbNoGenexus: saída de pacotes .xml e, quando necessário, .xpz.xpz consumido pode ser renomeado para processado_<nome-original>.xpzprocessado_processado_, tratar isso como alerta operacional de naming inconsistente, pedir confirmação antes de seguir e deixar o InputPath informado prevalecer se o usuário confirmarscriptsTempXpzExportadosPelaIDEObjetosDaKbEmXmlKbIntelligenceObjetosGeradosParaImportacaoNaKbNoGenexusPacotesGeradosParaImportacaoNaKbNoGenexusXpzExportadosPelaIDE ainda não existir, perguntar onde o usuário quer salvar os .xpzObjetosDaKbEmXml ainda não existir, parar e tratar a KB como ainda não materializadaXPZ exportado pela IDE para consulta futura do agente:
full.xmlXPZ parcial:
NomeCurto_GUID_YYYYMMDDXPZ exportado pela IDE:
XPZXPZ, organizar os arquivos em subpastas por tipo amigável de objeto GeneXusXPZ, usar nomes amigáveis dos objetos como nome principal dos XMLsparentGuid, parentType e moduleGuid servem como metadados de apoio, não como eixo principal de organizaçãogit rev-parse --show-toplevel)scripts\ e identificar os dois wrappers pelo README.md localOs wrappers seguem esta convenção de parâmetros:
-InputPath (obrigatório) — caminho para .xpz, XML ou pasta contendo o XML-VerifyOnly (switch) — só confere, não regrava-FullSnapshot (switch) — compara snapshot completo do acervo-FullSnapshot, o motor reconcilia o acervo pela identidade estável do nó raiz (guid), não só pelo nome lógico: quando o mesmo guid aparece no acervo sob nome de arquivo diferente, trata como rename e renomeia o arquivo existente (Move-Item antigo → novo) em vez de criar-novo + abandonar-antigo; o resultado é um arquivo só (nome novo) e o git detecta rename por similaridade. Cobre Attribute e Object. Em -VerifyOnly, o motor apenas classifica o resíduo de rename no relatório (RenameResidualsDetected), sem tocar o discoXPZ full define apenas o insumo; não define, por si só, o modo de verificaçãoXPZ full vindo da IDE ou por export headless via MSBuild, não presumir -FullSnapshot como padrão implícito nem como atalho ergonômico-FullSnapshot somente em um destes casos: pedido explícito do usuário por conferência full, uso do wrapper específico de conferência full, ou exigência nominal da documentação local do repositório-ReportPath (opcional) — salva relatório JSON-KeepReport (switch) — mantém relatório mesmo sem erromaterializacao e qual corresponde a confirmacao/conferencia-ExpectedItems (opcional) — lista de itens esperados da frente atual no formato Tipo:Nome, usada apenas para classificação comparativa entre foco esperado e retorno oficial da KB-ExpectedItems como lista normal de PowerShell
ou como string única separada por vírgula, ponto e vírgula ou quebra de linha;
ao invocar via pwsh -File a partir de Bash/CMD, preferir a string única
separada por vírgula para evitar ambiguidade de parser entre shells-ExpectedItems, mas a execução falhar no motor
compartilhado efetivo por incompatibilidade restrita a esse opcional
comparativo, tratar como divergência wrapper/engine e não como bloqueio
automático do sync principal-ExpectedItems,
concluir a materialização se o restante do fluxo estiver são e registrar no
handoff que a comparação esperada x retorno oficial ficou indisponível naquela
rodada por incompatibilidade do engine-ExpectedItems revelar quebra da materialização,
contrato principal do wrapper, refresh obrigatório do índice ou outro impacto
central no fluxo oficial, continuar tratando o caso como bloqueio real-KbMetadataPath (opcional) — salva metadados da KB em formato Markdown-ParallelKbRoot (opcional) — raiz da pasta paralela; resolve scripts/gx-object-type-catalog.override.json-CatalogOverridePath / -DiscoveryReportPath (opcionais) — override local e relatório JSON quando o pacote tiver GUID não mapeadokb-source-metadata.md faz parte normal do fluxo; o motor scripts/Sync-GeneXusXpzToXml.ps1 (via scripts/XpzKbSourceMetadataEditSupport.ps1) atualiza cirurgicamente somente campos de materialização (updated, last_xpz_materialization_run_at, source_xpz, source_refresh_status e tabelas KMW/Source/Source/Version), preservando last_setup_audit_run_at, setup_contract_signature_*, demais frontmatter e seções fora do escopo, com EOL dominante via scripts/XpzTextFileEolSupport.ps1kb-source-metadata.md for atualizado pelo sync, ele deve registrar last_xpz_materialization_run_at como horário do processamento XPZ/XML solicitado, mesmo quando nenhum XML tiver mudança materialXPZ vier com Source vazio, incompleto ou ausente, o wrapper deve preservar valores estáveis conhecidos e emitir warning de refresh parcial; isso não invalida o sync de objetosObjetosDaKbEmXml, o wrapper local deve acionar compulsoriamente a regeneração/validação do índice derivado por wrapper local de KbIntelligencescripts/Build-KbIntelligenceIndex.ps1 exige Python 3.x utilizável no PATH (scripts/GeneXusPythonPrerequisite.ps1; stub da Microsoft Store em WindowsApps não conta). Ausência bloqueia o refresh com exit 8 e mensagem PREREQUISITO AUSENTE — rigor: sync normal não terminou; a materialização XPZ/XML pode já ter concluído, mas isso não equivale a sucesso do fluxo oficial nem autoriza triagem ampla sem índice. Não tratar como falha do pacote exportado; instalar Python 3.x e rerodar o rebuild (Rebuild-*KbIntelligenceIndex.ps1). Ver README.md, 02-regras-operacionais-e-runtime.md e molde Update-KbFromXpz.example.ps1README.md/AGENTS.md ou chamada observável no próprio wrapper local; não presumir essa capacidade apenas porque a base compartilhada a exigexpz-kb-parallel-setup antes de seguirsync seguido de regeneração manual separada do índice como fluxo normal em pasta que adota KbIntelligence-BlockCrossFlowDataSource (switch, opt-in) — aborta o sync (ErrorId=CrossFlowDataSourceCollisionBlocked, precedido de CROSSFLOW_BLOCKED_ERRORID: no stderr) antes de gravar metadata ou XML quando há colisão cross-fluxo de origem (dataSource): moderno (sem dataSource) ↔ legado (gx-legacy-export)CrossFlowCollisions; stderr/relatório), e o fluxo segue normalmente pela regra de lastUpdate (sobrescreve se o entrante não for mais antigo), podendo materializar moderno↔legado sem bloquear; ver detalhe na seção de interpretação de resultado-ExpectedItems), não como bloqueio-NoGitSummary (switch) — suprime resumo Git no final-InputPath (obrigatório) — caminho para .xpz, XML ou pasta-ReportPath (opcional) — salva relatório JSON-KeepReport (switch) — mantém relatório mesmo sem erroxpz-kb-parallel-setupREADME.md local para identificar os nomes dos wrappersObjetosDaKbEmXml = snapshot oficial da KB, materializado em XMLs individuais por objeto e atualizado apenas pelo fluxo oficial do scriptXpzExportadosPelaIDE = entrada dos .xpz exportados pela IDEObjetosGeradosParaImportacaoNaKbNoGenexus = área de trabalho para XML local de importação manual, organizada por frente em subpastas NomeCurto_GUID_YYYYMMDDPacotesGeradosParaImportacaoNaKbNoGenexus = área de pacotes gerados localmente, mantida plana sem subpastas por frentescripts = wrappers .ps1 que tratam os XPZObjetosGeradosParaImportacaoNaKbNoGenexusObjetosDaKbEmXml, reportar isso como incidente de processo:
ObjetosGeradosParaImportacaoNaKbNoGenexusObjetosDaKbEmXml para a versão oficial do GitObjetosGeradosParaImportacaoNaKbNoGenexus, não no acervo oficial
7b. Lembrete/auditoria de override de catálogo (cada sessão): se a pasta paralela tiver scripts/gx-object-type-catalog.override.json, executar Test-XpzCatalogOverrideSessionReminder.ps1 -ParallelKbRoot <raiz> -AsJson e ler status, noticeRequired, reminderRequired, cleanupRecommended, declaredUpstreamPending, effectiveUpstreamPending e listas pendingTypeNames/redundantTypeNames/divergentTypeNames. Repetir ao usuário a mensagem quando reminderRequired=true; quando cleanupRecommended=true, oferecer limpeza local aprovada das entradas redundantes no plano da rodada, sem remover automaticamente.
7c. Pré-varredura antes de materialização longa: para XPZ full ou primeira carga, rodar Get-GeneXusImportPackageObjectInventory.ps1 com -FailOnUnknownTypes e -ParallelKbRoot (a saída de máquina é JSON por padrão no stdout, sem -AsJson). Se bloquear (exit 3 / UNKNOWN_TYPES_BLOCKED), não chamar sync até resolver o tipo.
7d. Tipo desconhecido detectado: seguir 02 / 08 (seção tipo desconhecido): parar; perguntar se o usuário autoriza consulta recomendável a nexa + wiki oficial; oferecer registro local com -UserApproved (Register-GeneXusObjectTypeCatalogOverride.ps1) e prompt ao mantenedor (New-GeneXusUnknownTypeMaintainerPrompt.ps1). Usar -DiscoveryReportPath no sync para JSON de triagem em Temp.InputPath com o usuário se não foi fornecidoXPZ completo:
full.xml em XMLs individuais por objetoXPZ parcial:
XPZ for reexportado/atualizado e reprocessado, tratar o novo processamento pelo conteúdo e pelo lastUpdate resultante, não pela memória do processamento anterior-ExpectedItems, usar esse contexto apenas para comparar foco esperado versus retorno oficial; a materialização continua seguindo tudo que a KB devolveu oficialmenteKbIntelligence, validar que o wrapper local de materialização encadeia refresh compulsório do índice após sync bem-sucedido que não seja VerifyOnly
xpz-kb-parallel-setupkb-source-metadata.md e depois regenerar o índice manualmente como substituto da correção de compatibilidade.example.ps1 da base compartilhada como substituto temporário do wrapper local real ausenteXPZ em ObjetosDaKbEmXml, não acrescentar -FullSnapshot por conta própriaXPZ full como autorização implícita para -FullSnapshot; export full e conferência full são coisas diferentes-FullSnapshot apenas quando o usuário pedir conferência full, quando o wrapper específico de conferência for o escolhido ou quando a documentação local tornar isso requisito explícitoprocessado_ como heurística forte de artefato já consumido, não como verdade absoluta sobre o conteúdo do arquivoInputPath explicitamente informado pelo usuário apontar para arquivo com prefixo processado_, emitir alerta curto, pedir confirmação e prosseguir somente se o usuário confirmar esse arquivo como insumo correto da rodada atual-ExpectedItems, lembrar que a
exposição no wrapper local não prova compatibilidade integral do motor
compartilhado efetivo; se a primeira execução falhar apenas nesse ponto,
preparar rerun sem o opcional antes de concluir bloqueio do syncpwsh -File ...
ObjetosDaKbEmXml foi concluída com sucesso e não era VerifyOnly, confirmar na saída do wrapper ou em evidência local clara que o refresh compulsório do índice derivado também foi executado
PREREQUISITO AUSENTE / exit 8 do motor Python, declarar fluxo incompleto (XMLs possivelmente atualizados, índice pendente); não fechar como sync OK nem como defeito do XPZKbIntelligence, ausência de evidência do refresh deve ser tratada como falha ou defasagem operacional do wrapper localxpz-kb-parallel-setup.xpz consumido para processado_<nome-original>.xpzMaterializationInterpretation, usar esse campo como leitura principal do resultado em vez de inferir pela combinação solta de Created, Updated e Unchanged-FullSnapshot reconciliar rename por guid, reportar RenamedByGuid (arquivos renomeados no acervo ou órfãos de mesmo guid removidos); em -VerifyOnly, reportar RenameResidualsDetected (renames detectados sem mover); esses números explicam por que um nome antigo deixou de existir no acervo e devem ser lidos como rename reconhecido, não como deleção cegaKind = "xpz-sync-result", SchemaVersion = 1, serializada com -Compress); todo texto humano (resumo de contadores, resumo Git, avisos) sai no stderr, nunca no stdout. Consumir o resultado como objeto (ConvertFrom-Json), não parsear o texto humano. Atenção: em processo filho (pwsh -File), Write-Host/Write-Warning/Write-Information vazam para o stdout capturado — por isso o contrato exige stderr para diagnósticogit diff para nomear os objetos: CreatedNames, UpdatedNames, UnchangedNames, SkippedOlderLastUpdateNames (formato "Tipo:Nome") e RenamedByGuidItems ({Guid, FolderType, OldName, NewName, Action}). Cada lista é consistente com o contador homônimo (len(UpdatedNames) == Updated, etc.). Em -VerifyOnly as listas de writes vêm vazias por construção (não por ausência de dado); NormalizedFileNames permanece só como contador (é nome de arquivo, não nome lógico)git diff)updated significa que o wrapper materializou conteúdo mais novo/relevante para o acervo naquele processamentounchanged significa que o item já tinha no acervo oficial conteúdo compatível ou mais novo, tipicamente com lastUpdate igual ou superior ao XML vindo do XPZupdated/unchanged pertencem ao processamento do XPZ contra o arquivo materializado atual, não ao estado Git do repositórioprimeira carga ou equivalente quando Created = 0 e Unchanged > 0; essa combinação, sozinha, não comprova primeira materialização e normalmente indica snapshot já existente confirmado contra o insumo atualunchanged no sync porque o arquivo local já está igual ao conteúdo vindo do XPZ, mesmo que esse mesmo arquivo ainda tenha diff pendente no Git contra o último commitdataSource): o motor detecta, antes de gravar metadata/XML, quando um item entrante colide no acervo (FolderType|NormalizedName) com um arquivo de origem diferente — caso central moderno (sem dataSource) ↔ legado (dataSource="gx-legacy-export"). Postura padrão fail-soft: campo aditivo CrossFlowCollisions (array; [] quando vazio) no resultado do stdout + booleano Writes[].CrossFlowCollision no $report (-ReportPath); cada colisão também sai por stderr em JSONL com prefixo CROSSFLOW_COLLISION: (e warnings de parse em CROSSFLOW_WARNING:), para não se perder nos caminhos que abortam antes do stdout. SchemaVersion permanece 1 (campos aditivos). Decisão E.2: quando o arquivo existente não tem dataSource, o filho direto <GxLegacyPayload> é o sinal de legado; guid="" só corrobora.-BlockCrossFlowDataSource (bloqueio opt-in): aborta o sync (terminating error ErrorId=CrossFlowDataSourceCollisionBlocked, precedido da linha estável CROSSFLOW_BLOCKED_ERRORID: no stderr) antes de gravar qualquer metadata ou XML, em vez do fail-soft. Separado do fail-closed de pacote misto. Para um XML existente não-parseável (Decisão G): a detecção não gera colisão nem bloqueia (nem sob o switch), só um warning — mas não garante a sobrescrita; o sync pode falhar adiante ao processar um arquivo existente corrompido (estágios de parse preexistentes, fora do escopo desta frente).$items e antes da metadata, em ambos os ramos. No ramo moderno isso reordenou o fluxo para catálogo → tipo-desconhecido → Convert → detecção → metadata: os fail-closed de tipo desconhecido e de colisão intra-pacote passam a abortar antes da gravação de kb-source-metadata.md (antes a metadata era gravada e só então falhavam). Assimetria: o fail-closed de rename sob -FullSnapshot (Resolve-GuidAwareRenames) continua abortando após a metadata (preexistente, fora do escopo) — sob -FullSnapshot, esse caminho pode deixar a metadata gravada sem writes.XPZ tiver sido reprocessado após atualização do arquivo, deixar explícito que a comparação relevante é com o conteúdo do insumo reprocessado e com o estado atual do acervo, não com o relatório antigokb-source-metadata.md tiver sido atualizado cirurgicamente pelo wrapper (campos de materialização), tratar isso como artefato normal do fluxo, não como evidência automática de mudança funcional na frenteObjetosDaKbEmXml não foi materializada, aguardando primeiro XPZ ou equivalente, atualizar ou neutralizar esse estado quando a primeira materialização oficial tiver sido concluída com sucessokb-source-metadata.md, como versão do GeneXus, build, GUID da KB, usuário ou caminho Source, quando esse metadado tiver aparecido explicitamente na saída real do wrapper ou quando o próprio kb-source-metadata.md tiver sido aberto e lido nominalmente na rodada atualSource parcial, separar claramente sync de objetos aceito de refresh de metadado parcial e preservar os valores estáveis já conhecidosXPZ oficial da KB trouxer objetos adicionais fora do foco imediato da frente, reportar isso como inesperado para a frente atual, mas tratar como possível mudança paralela legítima vinda da IDE/KB até evidência em contráriogit diff --check apontar whitespace em ObjetosDaKbEmXml, distinguir whitespace herdado literalmente do export oficial da IDE de whitespace introduzido antes pelo agente em XML/pacote local; o sync não deve reformatar automaticamente o snapshot oficial só para limpar ruído histórico-ExpectedItems estar disponível no wrapper: objetos-foco que voltaram, objetos-foco que não voltaram e retorno oficial adicional da KB-ExpectedItems tiver sido informado, classificar explicitamente itens esperados que voltaram, itens esperados que não voltaram e retorno oficial adicional da KB-ExpectedItems foi informado, as listas ExpectedReturnedNames, ExpectedMissingNames e AdditionalOfficialNames (listas "Tipo:Nome" achatadas no resultado JSON) são a fonte nominal direta das três partes — respectivamente objetos-foco que voltaram, não voltaram e retorno oficial adicional. As listas por status (CreatedNames/UpdatedNames/...) são eixo ortogonal: dizem o que foi escrito no acervo, não o que era esperado pela frente; sem -ExpectedItems, as três partes vêm do julgamento do agente sobre os objetos-foco, não de *Names-ExpectedItems tiver sido informado, emitir também um resumo humano curto no console/handoff, sem alarmismo e sem tratar adicionais oficiais ou esperados ausentes como falha automática-ExpectedItems por divergência
wrapper/engine, separar explicitamente sync principal concluído de
comparação opcional indisponível nesta rodadaxpz e for materializado no acervo oficial, tratar esse XML do acervo como a fonte mais confiável para alterações futuras; não reutilizar cópia intermediária/delta sem comparar com o acervo atualizadosync, separar explicitamente:
XPZ, ainda que fora do foco imediato da frenteInputPath usadoMaterializationInterpretation quando o wrapper expuser esse campo; caso contrário, limitar a leitura aos contadores e warnings reaiskb-source-metadata.md foi lido nominalmente na rodada atual ou apenas atualizado cirurgicamente pelo wrapper (campos de materialização)objetos-foco que voltaram, objetos-foco que não voltaram e retorno oficial adicional da KB — mesmo quando -ExpectedItems não foi passado ou não está disponível no wrappergit add, commit ou pushPastaParalelaDaKb/
XpzExportadosPelaIDE/
KBCompleta_20260413.xpz
processado_AjustesFinanceiro_20260413.xpz
ObjetosDaKbEmXml/
Transaction/
Cliente.xml
Pedido.xml
Procedure/
GeraBoleto.xml
WebPanel/
WPClienteConsulta.xml
ObjetosGeradosParaImportacaoNaKbNoGenexus/
AjusteVolumes_12345678-1234-1234-1234-123456789abc_20260414/
ClienteNovo.xml
PedidoAjustado.xml
PacotesGeradosParaImportacaoNaKbNoGenexus/
AjusteVolumes_12345678-1234-1234-1234-123456789abc_20260414_01.import_file.xml
scripts/
Sync-GeneXusXpzToXml.ps1
kb-source-metadata.md
O arquivo kb-source-metadata.md, quando exposto pelo wrapper local via
-KbMetadataPath, é artefato normal de processamento e recebe atualizacao
cirurgica em cada sync (não regeneracao total do arquivo). O motor preserva
last_setup_audit_run_at (autoridade de xpz-kb-parallel-setup), demais
frontmatter fora do escopo do sync e seções extras; atualiza valores estaveis de
Source/KMW quando o XPZ atual vier com metadados vazios ou parciais.
Esse arquivo também é o local esperado de last_xpz_materialization_run_at
(autoridade desta skill).
Esse horário representa a última solicitação/processamento de materialização
XPZ/XML, não apenas a última mudança material detectada nos XMLs.
O Sync-GeneXusXpzToXml.ps1 reconhece e materializa exports legados GeneXus 9
sem configuração extra. Um export legado é um ExportFile cujos objetos aparecem como
<GXObject><Elemento> por nome (ex.: <Procedure>, <Report>), sem Object/@type
(GUID de tipo) — diferente do export moderno GeneXus 18. Detecção automática por perfil:
/ExportFile/GXObject e Objects/Object=0 e Attributes/Attribute=0;ExportFile) = fail-closed: o sync
lança erro BLOCK sem gravar kb-source-metadata.md e sem materializar nada. Exporte
os formatos separadamente.No ramo legado o motor (scripts/GeneXusLegacyExportFileSupport.ps1) consome o registro
scripts/gx-legacy-export-element-registry.json (doc-dono 01k-registro-elementos-legados.md):
equivalent → materializa no folderName do tipo moderno, com type=<GUID real do catálogo>;orphan (Report/Menubar) → materializa em materializedFolderName próprio, com type="gxlegacy/<Elemento>";Object/Attribute com dataSource="gx-legacy-export", payload
original preservado em <GxLegacyPayload> e guid="" (não participa do rename por GUID);FolderType|NormalizedName já existir no acervo como
moderno (sem dataSource), a detecção cross-fluxo dispara ao materializar o legado —
fail-soft por padrão (CrossFlowCollisions), ou bloqueio com -BlockCrossFlowDataSource
(ver "Wrapper de atualização diária" e a seção de interpretação de resultado);lastUpdate ausente/inválido → sentinela determinística 0001-01-01T00:00:00.0000000Z
(conservadora: na materialização incremental, sentinela × data real → skipped-older-lastUpdate);throw com instrução de estender o registro (não materializa parcial).Sinais no JSON de resultado: LegacyFormatDetected=true e
MaterializationInterpretation/PackageInterpretation=legacy-export-adapted. Quando
-KbMetadataPath é informado, a metadata recebe -IsLegacyExport: o Build vem de
KMW/MaxGxBuildSaved (o export legado não traz KMW/Build nem bloco <Source>), com um
hint dedicado no lugar do warning genérico de Source ausente. A leitura é encoding-aware
(export GX9 é iso-8859-1, lido por XmlDocument.Load). Ver 01k, 02 e xpz-reader/SKILL.md.
README.md localsync normal enquanto a pasta paralela da KB ainda estiver indefinida, não montada ou não validada.xpz para dentro de XpzExportadosPelaIDE como se essa pasta fosse saída do agente; ela é a entrada gravada pelo usuário/IDE.xpz para processado_<nome-original>.xpz antes de sucesso claro no processamentoprocessado_XPZ completo ou parcial na pasta de geração para importaçãoObjetosGeradosParaImportacaoNaKbNoGenexus como snapshot oficial ou como lote ativo de importaçãoguid, parentGuid, parentType ou moduleGuid como eixo principal de navegaçãoObjetosDaKbEmXml fora do fluxo oficial do script .ps1KbIntelligenceKbIntelligence se o wrapper local de materialização ainda não encadeia refresh compulsório do índice; oferecer atualização via xpz-kb-parallel-setupsync seguido de rebuild manual separado do índice como fluxo normal em pasta que adota KbIntelligenceprocessado_ quando houver outros candidatos plausíveis para a rodada atualprocessado_ como bloqueio absoluto quando o usuário tiver apontado explicitamente o InputPath; primeiro emitir alerta operacional e exigir confirmação explícitaObjetosDaKbEmXmlObjetosDaKbEmXml estiver dirty fora do fluxo oficial; primeiro preserve, restaure e trate como incidente de processoObjetosDaKbEmXml para delta ainda não reexportado oficialmente pela KB como detalhe operacional; isso é erro explícito de processoObjetosGeradosParaImportacaoNaKbNoGenexus como lote ativo de importação; o lote ativo deve viver na subpasta da frente NomeCurto_GUID_YYYYMMDDPacotesGeradosParaImportacaoNaKbNoGenexus; essa area de pacotes deve permanecer planascripts/XPZ atualizado como se o resultado anterior ainda fosse autoritativokb-source-metadata.md pelo wrapper (campos de materialização) como mudança funcional automática da frente atualkb-source-metadata.md perder valores estáveis conhecidos porque o XPZ veio com Source vazio ou incompletolast_setup_audit_run_at nem outros campos de frontmatter fora da autoridade do sync; a gravacao desse campo pertence a xpz-kb-parallel-setup (Set-*KbSetupAuditTimestamp.ps1 / scripts/Set-XpzSetupAuditTimestamp.ps1)ObjetosDaKbEmXml durante sync para remover whitespace herdado de export oficial; se o ruído tiver sido introduzido por XML/pacote local gerado pelo agente, a correção deve acontecer na etapa de geração em ObjetosGeradosParaImportacaoNaKbNoGenexus antes da importação, não como limpeza posterior do snapshot oficialXPZ oficial vindo da KB trazer objetos adicionais além do foco da frenteXPZ com tipo desconhecido no catálogo efetivo (compartilhado + override aprovado)ExportFile misto (elementos legados <GXObject> e modernos <Objects>/<Attributes> no mesmo pacote); é fail-closed (throw sem gravar kb-source-metadata.md) — exportar os formatos separadamentegx-legacy-export-element-registry.json; o motor lança throw pedindo para estender o registro (doc-dono 01k), nunca improvisar pasta/tiponexa/wiki sem consentimento explícito do usuárioTest-XpzCatalogOverrideSessionReminder.ps1 retornar noticeRequired=true: reminderRequired=true exige alerta de pendência/divergência; cleanupRecommended=true exige oferta explícita de limpeza local aprovada, sem remoção automáticaGeneXus-XPZ-Skills a partir da pasta paralela para “fechar” tipo novo sem troca de contextoobjetos-foco que voltaram, objetos-foco que não voltaram, retorno oficial adicional da KB) no handoff quando o contexto da conversa identificar uma frente ativa com objetos-foco conhecidos — isso é obrigatório independentemente de -ExpectedItems estar disponível no wrapper