xpz-kb-parallel-setup

name	xpz-kb-parallel-setup
description	Prepara e valida a estrutura inicial da pasta paralela da KB para carga inicial, sync de XPZ, índice derivado e artefatos de importação

xpz-kb-parallel-setup

Define e valida a estrutura inicial da pasta paralela da KB usada ao redor de uma Knowledge Base GeneXus. Essa estrutura não substitui a pasta nativa da KB; ela concentra os XPZ exportados pela IDE, os XMLs materializados pelo fluxo oficial, o índice derivado para triagem e os artefatos locais preparados para importação posterior.

---

GUIDELINE

Esta skill e de invocacao obrigatória antes de qualquer ação de consulta, triagem, leitura de XML ou geração de objeto em pasta que contenha ObjetosDaKbEmXml/ ou KbIntelligence/. Nenhuma outra skill de KB (xpz-index-triage, xpz-reader, xpz-builder, xpz-sync, nexa) pode ser iniciada nessa pasta enquanto esta skill não tiver sido executada na sessao corrente.

PRE-CONDICAO OBRIGATÓRIA AO SER INVOCADA PELO GATILHO GLOBAL (não se aplica quando o usuário pede explicitamente setup, atualizacao ou auditoria — nesses casos ir direto ao WORKFLOW passo 1):

Esta pre-condicao e o caminho leve de seguranca para tarefas normais do usuário na KB. Ela deve executar apenas runtime, freshness e gate de índice enquanto o freshness retornar GATE_ONLY e o índice retornar GATE_OK; não carregar nem aplicar o corpo completo do WORKFLOW nesse caminho curto. AUDIT_REQUIRED por assinatura de contrato de setup ausente, invalida ou defasada e comportamento deliberado: após git pull da base metodologica, a pasta paralela precisa ser conferida quando a superficie de contrato de xpz-kb-parallel-setup mudou, para saber se deve incorporar wrappers, gates, metadata ou regras locais novas. Commits em outras frentes do repositório que não alterem essa superficie não devem, por si só, disparar auditoria completa.

0. Verificar se Test-*KbPowerShellRuntime.ps1 existe em scripts/ da pasta paralela e executa-lo antes de qualquer outro wrapper:

   & "<caminho-absoluto-de-Test-*KbPowerShellRuntime.ps1>"
   

   • Se ausente: prosseguir com auditoria completa (WORKFLOW passo 1), mas classificar a pre-condicao como setup_bloqueado ate o wrapper ser criado via atualizar_bootstrap_local
   • Se retornar POWERSHELL_RUNTIME_OK: prosseguir para o passo 1
   • Se retornar BLOCK: ou falhar: registrar o erro e bloquear o uso operacional da pasta paralela ate existir pwsh com PowerShell 7.4 LTS ou superior
1. Verificar se Test-*KbSetupFreshness.ps1 existe em scripts/ da pasta paralela
   • Se ausente: prosseguir com auditoria completa (WORKFLOW passo 1)
2. Se presente, executar:

   & "<caminho-absoluto-de-Test-*KbSetupFreshness.ps1>"
   

2a. Declarar na conversa o resultado obtido pelo script antes de prosseguir: - se GATE_ONLY: registrar "Test-*KbSetupFreshness.ps1 retornou GATE_ONLY" - se AUDIT_REQUIRED: <motivo>: registrar "Test-*KbSetupFreshness.ps1 retornou AUDIT_REQUIRED — " - se script ausente (verificado no passo 1): registrar "Test-*KbSetupFreshness.ps1 ausente — auditoria completa necessária" - se erro inesperado: registrar o erro antes de decidir o próximo passo 3. Seguir o output:

• AUDIT_REQUIRED: <motivo> → prosseguir com auditoria completa (WORKFLOW passo 1)
• GATE_ONLY → executar Test-*KbIndexGate.ps1; se GATE_OK, liberar o fluxo normal; se BLOCK, prosseguir com auditoria completa (WORKFLOW passo 1)

O agente não deve raciocinar sobre timestamps por conta própria nem substituir a execução do script por verificacao manual de datas ou de arquivos.

Quando acionada pelo gatilho global, "auditoria completa" significa: executar Test-*KbPowerShellRuntime.ps1 antes dos demais wrappers; se ele estiver ausente ou retornar BLOCK:, classificar como setup_bloqueado e não executar uso operacional da pasta paralela. Com runtime aprovado, executar Test-*KbSetupAudit.ps1 (se existir), seguido de Test-*KbIndexGate.ps1 (se existir), verificar que estado_operacional_sugerido e compativel com a tarefa em curso e liberar o fluxo somente após GATE_OK. Depois da auditoria completa, o agente deve classificar explicitamente o subestado transitorio da PRE-CONDICAO antes de voltar a tarefa original; esses rotulos setup_* não são estados canonicos de conclusao e não devem ser usados como estado final do setup:

• setup_apto: auditoria passou, gate passou e não ha pendencia persistente identificada no motivo original do AUDIT_REQUIRED.
• setup_apto_com_metadata_pendente: auditoria passou e gate passou, mas o motivo original do AUDIT_REQUIRED foi ausencia, defasagem ou inconsistencia de campo persistente em kb-source-metadata.md, como last_setup_audit_run_at ou setup_contract_signature_*.
• setup_bloqueado: runtime PowerShell mínimo falhou/ausente, auditoria ou gate falhou, ou estado_operacional_sugerido não e compativel com a tarefa em curso.

Quando o motivo original do AUDIT_REQUIRED for assinatura de contrato de setup ausente ou defasada e a auditoria completa seguida do gate passar sem pendencia corrigivel, tratar a gravacao de last_setup_audit_run_at e setup_contract_signature_* como fechamento da pre-condicao bem-sucedida: incluir Set-*KbSetupAuditTimestamp.ps1 no plano consolidado, ou registrar recusa/adiamento explicito do usuário. Sem esse fechamento, a próxima sessao repetira a auditoria completa pelo mesmo motivo, mesmo com a pasta já conferida.

Se o subestado for setup_apto_com_metadata_pendente, o agente não pode prosseguir silenciosamente apenas porque o gate retornou GATE_OK. Antes de continuar a tarefa original, montar o plano consolidado de correcoes (seção PLANO DE CORRECOES POS-AUDITORIA), incluindo obrigatoriamente a linha de last_setup_audit_run_at e setup_contract_signature_* com Set-*KbSetupAuditTimestamp.ps1 quando a auditoria bem-sucedida permitir gravacao. Declarar que a tarefa atual está liberada pelo gate, mas a pasta repetira auditoria completa nas próximas sessoes enquanto o plano não for executado ou adiado explicitamente pelo usuário.

Quando estado_operacional_sugerido for atualizacao_metodologica_pendente: ler todas as linhas wrappers/inventario: da saida e incorporar cada pendencia (INVENTORY_GAPS, INVENTORY_SHORT_NAMING, INVENTORY_CUSTOMIZED, INVENTORY_LEGACY_ORPHANS, INVENTORY_RECOMMENDED_MISSING) ao plano consolidado de correcoes, com explicacao em portugues e sem termos tecnicos em ingles. Se houver tambem a linha consultiva INVENTORY_SURFACE_ADVISORY (que por si só NÃO leva a atualizacao_metodologica_pendente), incorpora-la ao mesmo plano como recomendacao de realinhamento de superficie, sem trata-la como bloqueio. Não acionar o WORKFLOW de criacao/documentacao (passos 1-7b) — esse WORKFLOW e reservado para quando o usuário pede explicitamente setup, atualizacao ou auditoria.

Quando a saida de Test-*KbSetupAudit.ps1 trouxer metadata wrapper: diferente de OK (PENDENTE_DE_DADOS, PENDENTE ou BLOCK), esse resultado também exige estado_operacional_sugerido=atualizacao_metodologica_pendente. GATE_OK, NAMING_OK e inventario sem gaps não neutralizam metadado de identidade ausente ou wrapper de metadata quebrado. O agente deve evidenciar a linha metadata wrapper.evidencia, distinguir campo ausente de falha funcional do wrapper e, quando a pendencia for identidade estavel ausente, oferecer reconciliacao via resolvedor/atualizador de identidade antes de declarar estado limpo.

Quando a saida trouxer metadata/deploy: diferente de OK (PENDENTE ou BLOCK), tratar como pendencia metodologica da mesma severidade: metadata wrapper: OK não prova plausibilidade semantica de kb_environment_names nem do mapeamento kb_environment_output_dirs/kb_environment_web_dirs. Para deployment_hosting_kind=java-tomcat, metadata/deploy: PENDENTE tambem pode significar ausencia dos campos dedicados kb_environment_servlet_dirs/kb_environment_app_package/kb_environment_servlet_flavor; nesse caso, usar o assistente read-only Resolve-XpzJavaTomcatMetadataSuggestion.ps1 apenas para produzir candidatos e evidencia, confrontar model.ini com gradle.properties/sentinelas/pacote e gravar por Set-*KbSourceMetadataDeployment.ps1 somente apos confirmacao explicita do usuário. O agente deve evidenciar metadata/deploy.evidencia, distinguir campos de deploy/output ausentes (PENDENTE) de metadata legado ou inconsistente (BLOCK), perguntar ao usuário os nomes exatos dos environments e os diretórios de output por environment, validar cada nome via MSBuild (SetActiveEnvironment headless) e rerodar Set-*KbSourceMetadataDeployment.ps1 com -KbEnvironmentNames, -KbEnvironmentOutputDirs e, quando aplicavel, campos Java/Tomcat opt-in antes de declarar estado limpo.

Após o setup ser concluido com sucesso, qualquer consulta de existência, localização ou triagem de XML deve ser roteada para xpz-index-triage antes de abrir arquivos individuais, quando a pasta adotar KbIntelligence.

Usar esta skill quando o trabalho exigir preparar, explicar, validar, atualizar ou corrigir a estrutura da pasta paralela da KB. O agente deve separar claramente a pasta nativa da KB da pasta paralela e aplicar os nomes padrão quando o usuário não informar alternativas.

Quando o usuário usar qualquer linguagem que sugira setup — "refazer", "reiniciar", "recriar", "atualizar", "preciso dos novos scripts", "meu gate ta falhando" ou equivalente — em pasta que já tem histórico real, assumir modo_atualizacao e confirmar brevemente com o usuário o que sera feito antes de gravar. Se o pedido for genérico, como "refazer o setup", "revisar o setup" ou equivalente, assumir por padrão a intencao auditar_setup ate que o usuário peca explicitamente corrigir_wrapper_local ou atualizar_bootstrap_local. Em pasta com histórico real, modo_criacao nunca e uma opção oferecida ou aceita; se o usuário insistir em apagar tudo ou recriar do zero, recusar, explicar que dados existentes não serao destruidos e redirecionar para modo_atualizacao.

Essa confirmacao breve antes de gravar deve ser textual, objetiva e aderente ao diagnostico em andamento. Não abrir menu, enquete, questionario ou lista de opções logo no inicio de modo_atualizacao quando a auditoria mínima obrigatória ainda não tiver sido concluida.

Em modo_atualizacao, a verificacao de naming de ObjetosDaKbEmXml não e opcional e não pode ser pulada mesmo quando todos os scripts forem EQUIVALENTE: para cada diretório presente na pasta, o agente deve ler pelo menos um XML, extrair o tipo canonico pelo GUID (ou pelo elemento raiz <Attribute>), comparar com o nome do diretório e reportar o resultado — conforme ou divergente — antes de declarar qualquer estado de conclusao.

Dentro de modo_atualizacao, separar primeiro a intencao operacional antes de avancar:

• auditar_setup: o usuário quer conferir se a pasta paralela está aderente, atualizada e coerente; a saida principal e diagnostico com estado operacional, classificação de scripts, pendencias e plano consolidado de correcoes oferecido para execução na mesma sessao
• corrigir_wrapper_local: o usuário quer corrigir um wrapper local defasado, quebrado ou reprovado por gate; a saida principal e edicao do wrapper, rerun do gate relevante e handoff atualizado
• atualizar_bootstrap_local: o usuário quer incorporar wrappers ou seções documentais ausentes previstos pela base metodologica; a saida principal e completar o bootstrap local faltante sem recriar a pasta

modo_atualizacao descreve o contexto da pasta; auditar_setup, corrigir_wrapper_local e atualizar_bootstrap_local descrevem a natureza do trabalho. Não tratar essas tres intencoes como se fossem a mesma coisa só porque acontecem na mesma pasta com histórico real.

Em auditar_setup, concluir primeiro a auditoria mínima obrigatória e, em seguida, montar e oferecer o plano consolidado de correcoes (seção PLANO DE CORRECOES POS-AUDITORIA) antes de qualquer outro próximo passo operacional. Antes disso, não oferecer sincronizar XPZ novamente, rebuild do indice ou equivalentes como resposta-padrao a um pedido de "refazer setup".

Quando auditar_setup detectar INVENTORY_SHORT_NAMING no campo wrappers/inventario da saida de Test-*KbSetupAudit.ps1: os scripts listados existem com naming curto (ex: Test-KbIndexGate.ps1) em vez do naming canonico com prefixo KB (ex: Test-wsEducacaoSpTesteKbIndexGate.ps1). Essa divergencia NÃO e opcional, NÃO pode ser descartada como "convencao consistente aceita", NÃO e neutralizada por GATE_OK, STRUCTURE_OK ou pelo fato de os scripts funcionarem operacionalmente. O naming curto e uma divergencia do padrão desta skill. O agente deve: classificar cada script SHORT_NAMING como CUSTOMIZADO com ação de renome na tabela de 8.h; oferecer atualizar_bootstrap_local para executar os renomes; incluir os renomes na lista de trabalho da sessao corrente — não adiar para sessao futura nem condicionar a confirmacao a que o usuário mencione o problema primeiro.

Quando auditar_setup detectar INVENTORY_CUSTOMIZED no campo wrappers/inventario da saida de Test-*KbSetupAudit.ps1: os scripts listados existem, mas divergem metodologicamente do exemplo canonico correspondente. Divergencia de #requires -Version e divergencia metodologica objetiva quando o exemplo canonico declara uma versão e o wrapper local declara outra versão, mesmo que a lógica funcional restante seja equivalente. A ausencia de repasse de -AsJson nos wrappers K8/K9 Test-*KbSetupAudit.ps1/Test-*KbIndexGate.ps1 (motivo missing_AsJson_passthrough) e outra divergencia metodologica objetiva. O repasse, a um motor compartilhado advanced, de um parametro que o motor nao declara (motivo forwards_unknown_engine_param), um caminho de motor inferido inexistente na base canonica (motivo shared_engine_unresolved), a saida insegura exit $LASTEXITCODE em wrapper auditado que chama motor PowerShell por variavel (motivo unsafe_last_exitcode_after_ps1_engine) e a PERDA de contrato obrigatorio da superficie do molde (motivo surface_mismatch — obrigatorio do molde ausente/rebaixado ou param() de topo ausente com molde obrigatorio, pelo diff de superficie param()/ValidateSet), são igualmente divergencias metodologicas objetivas detectadas mecanicamente pelo inventario. O agente deve classificar cada script listado como CUSTOMIZADO na tabela de 8.h, evidenciar o motivo emitido pelo inventario e não declarar wrappers_atualizados nem materializado_e_indice_validado como estado limpo ate haver decisão explicita sobre a correcao.

Quando auditar_setup detectar INVENTORY_LEGACY_ORPHANS no campo wrappers/inventario da saida de Test-*KbSetupAudit.ps1: os scripts listados são nomes antigos que permaneceram na pasta scripts/ depois que o nome canonico atual já existe. Isso e pendencia metodologica objetiva porque mantem allowlists e documentação local apontando para comandos antigos. O agente deve classificar o arquivo legado como CUSTOMIZADO/legado na tabela de 8.h, oferecer remocao segura e atualizacao de referencias em .claude\settings.json, AGENTS.md, README.md e scripts locais, sempre com aprovacao explicita antes de apagar ou editar.

Quando auditar_setup detectar metadata wrapper: PENDENTE_DE_DADOS, metadata wrapper: PENDENTE ou metadata wrapper: BLOCK, ou metadata/deploy: PENDENTE ou metadata/deploy: BLOCK, não declarar materializado_e_indice_validado nem gravar last_setup_audit_run_at e setup_contract_signature_* como conclusao bem-sucedida. Se o próprio estado_operacional_sugerido ainda vier limpo nesse cenário, tratar como divergencia do motor de auditoria e corrigir a metodologia antes de usar o resultado para liberar a pasta.

PLANO DE CORRECOES POS-AUDITORIA

Aplica-se sempre que esta skill tiver concluido auditoria mínima — seja em auditar_setup, no BLOCO DE ATUALIZACAO de modo_atualizacao ou na auditoria completa da PRE-CONDICAO do gatilho global (após Test-*KbSetupAudit.ps1 e Test-*KbIndexGate.ps1 com GATE_OK, quando aplicavel). Não substitui as regras de aprovacao explicita antes de gravar; consolida o que oferecer corrigir e em que ordem, para o usuário não precisar descobrir pendencia por pendencia.

Objetivo

Ao terminar a auditoria, o agente deve entregar ao usuário:

1. Diagnostico (estado operacional canonico, dimensoes do Test-*KbSetupAudit.ps1 quando existir, tabela 8.h quando modo_atualizacao).
2. Plano consolidado de correcoes — lista única de itens corrigiveis nesta pasta segundo esta skill, cada um com ação proposta, pre-requisito de aprovacao (sim/nao) e skill/intencao usada (atualizar_bootstrap_local, corrigir_wrapper_local, passo 34, etc.).
3. Oferta em lote: perguntar se deseja executar o plano (ou subconjunto) agora nesta sessao; não encerrar com apenas "fica pendente" nem recomendar rodada futura por padrão.

GATE_OK pode liberar a tarefa original do usuário em paralelo ao plano, mas não dispensa apresentar o plano quando houver item corrigivel.

Itens que entram no plano (quando detectados)

Consolidar todos os itens abaixo que a auditoria tiver identificado; omitir um item da lista e proibido quando a evidencia existir:

Origem tipica	Item no plano	Ação preferida	Aprovacao antes de gravar
setup_apto, setup_apto_com_metadata_pendente ou passo 34 após AUDIT_REQUIRED	last_setup_audit_run_at ou setup_contract_signature_* ausente, vazio ou defasado após auditoria OK; inclui contrato de setup atualizado	Set-*KbSetupAuditTimestamp.ps1; rerodar freshness e index gate	Sim, se regra local exigir
INVENTORY_GAPS / scripts AUSENTE em 8.h	Wrappers ou gates ausentes previstos	atualizar_bootstrap_local a partir dos .example.ps1	Sim
INVENTORY_SHORT_NAMING	Naming curto de wrapper	Renome canonico em lote (8.c exceção 2)	Sim, confirmacao em lote
INVENTORY_LEGACY_ORPHANS	Script legado lado a lado com canonico	Remocao segura + atualizar referencias (8.f.1)	Sim
INVENTORY_CUSTOMIZED (não SHORT_NAMING)	Wrapper divergente do exemplo	Menu 8.c ou caso deterministico → corrigir_wrapper_local	Sim, por script ou lote
INVENTORY_SURFACE_ADVISORY (consultivo, não bloqueia)	Wrapper local defasado do molde por reducao opcional/ValidateSet (diff de superficie param())	Realinhar a superficie ao molde preservando defaults locais; nunca recopiar integral	Sim, se o usuário optar por realinhar
Caso deterministico (8.a.iii, 8.z)	Wrapper defasado com correcao inequivoca	corrigir_wrapper_local sem menu A/B/C/D	Sim, se regra local exigir
metadata wrapper ≠ OK	Identidade ou contrato de metadata	Reconciliacao via Resolve-*KbIdentity / Update-*KbMetadataIdentity ou corrigir wrapper	Sim
metadata/deploy ≠ OK	Plausibilidade de environment/deploy/output em kb-source-metadata.md; em java-tomcat, também metadata de WEB-INF\classes/pacote/flavor	Perguntar nomes e diretórios de output ao usuário, usar Resolve-XpzJavaTomcatMetadataSuggestion.ps1 como assistente read-only quando aplicavel, rerodar Set-*KbSourceMetadataDeployment.ps1 com -KbEnvironmentNames + -KbEnvironmentOutputDirs + campos Java opt-in + validação MSBuild; corrigir wrapper se uses_removed_inventory_discovery ou parâmetro obrigatório de environment/output ausente; tratar ausência de parâmetro Java/Tomcat opt-in indicada por INVENTORY_SURFACE_ADVISORY como realinhamento consultivo de superfície	Sim
declarativo/timestamps=DRIFT_TIMESTAMPS_LITERAIS	Timestamps literais em AGENTS.md/README.md	Substituir por ponteiros (examples/AGENTS.md.example)	Sim
Seção ## Triagem Por Indice ausente (8.g)	Roteamento para xpz-index-triage	Inserir bloco padrão no AGENTS.md local	Sim
INVENTORY_RECOMMENDED_MISSING	Wrappers finos recomendados	Criar a partir dos .example.ps1	Sim
Naming divergente em ObjetosDaKbEmXml (8.g2)	Diretórios com tipo real ≠ nome da pasta	Renome seguro com aprovacao	Sim
Prefixo verbal defasado (8.f)	Nome local ≠ exemplo canonico (Update- vs Rebuild-, etc.)	Renome + atualizar referencias	Sim
Test-*KbPowerShellRuntime.ps1 ausente	Runtime gate ausente	Incorporar wrapper de runtime	Sim

Itens que não entram no plano desta skill

Não prometer no plano consolidado o que pertence a outra frente, salvo mencionar como fora de escopo com skill responsável:

• Materialização XPZ/XML, sync de acervo, last_xpz_materialization_run_at → xpz-sync
• Rebuild/regeneracao de índice quando defasado por materialização → wrappers de índice + xpz-sync encadeado
• Import/build MSBuild, empacotamento de negocio, geração de objetos → skills respectivas
• Scripts CUSTOMIZADOS com divergencia editorial de lógica sem correcao deterministica → entram no plano como decisão do usuário (8.c), não como "correcao automática"

Ordem de execução sugerida no plano

Quando o usuário aprovar o pacote, executar na ordem abaixo salvo bloqueio concreto:

1. Test-*KbPowerShellRuntime.ps1 presente e OK (se estava ausente).
2. Casos deterministicos de wrapper (corrigir_wrapper_local) que desbloqueiam gates.
3. atualizar_bootstrap_local para scripts AUSENTE e renomes SHORT_NAMING.
4. Limpeza de legados orfaos e alinhamento de prefixos verbais (8.f / 8.f.1).
5. Drift declarativo (AGENTS.md/README.md) e seção de triagem por índice.
6. Metadata de setup (Set-*KbSetupAuditTimestamp.ps1) quando auditoria bem-sucedida permitir.
7. Reconciliacao de identidade estavel quando metadata wrapper exigir.
8. Gravacao de environment/deploy/output (Set-*KbSourceMetadataDeployment.ps1 com -KbEnvironmentNames e -KbEnvironmentOutputDirs confirmados pelo usuário + validação MSBuild obrigatória; em java-tomcat, campos Java opt-in sugeridos por Resolve-XpzJavaTomcatMetadataSuggestion.ps1 e confirmados pelo usuário) e correcao do wrapper local quando metadata/deploy, uses_removed_inventory_discovery ou parâmetro obrigatório de environment/output ausente exigirem. Se INVENTORY_SURFACE_ADVISORY indicar ausência de parâmetro Java/Tomcat opt-in no wrapper, oferecer realinhamento consultivo de superfície ao molde, preservando defaults locais; não tratar isso como bloqueio por INVENTORY_CUSTOMIZED. Imediatamente após gravar campos de deploy, reexecutar Test-*KbMetadataWrapper.ps1: a gravacao torna obrigatório que Get-*KbMetadata.ps1 exponha os campos novos, então um leitor antes aprovado pode passar a bloquear com BLOCK: <campo> existente no metadata nao foi exposto pelo wrapper. Quando isso ocorrer, e o caso deterministico de 8.a.iii — alinhar Get-*KbMetadata.ps1 ao exemplo canonico antes de seguir, sem abrir menu A/B/C/D.
9. Wrappers INVENTORY_RECOMMENDED_MISSING e naming de ObjetosDaKbEmXml aprovados pelo usuário.
10. Rerodar Test-*KbSetupAudit.ps1, Test-*KbSetupFreshness.ps1 (se existir) e Test-*KbIndexGate.ps1; atualizar handoff.

PRE-CONDICAO do gatilho global

Depois de classificar o subestado transitorio (setup_apto, setup_apto_com_metadata_pendente, setup_bloqueado):

• Se setup_bloqueado: não voltar a tarefa original; plano só com o que for corrigivel para destravar.
• Se setup_apto ou setup_apto_com_metadata_pendente com itens corrigiveis: montar o plano consolidado antes de retomar a tarefa original; itens de metadata pendente entram como linhas do plano, não como único aviso solto. Quando o único item for atualizar last_setup_audit_run_at e setup_contract_signature_* após auditoria bem-sucedida exigida por assinatura de contrato ausente ou defasada, ele ainda deve aparecer no plano para restaurar o caminho GATE_ONLY das próximas sessoes.
• Registrar decisão do usuário sobre o plano: executado (total/parcial), recusado ou adiado — só entao retomar a tarefa original liberada pelo gate.

Fechamento de auditar_setup

auditar_setup não fecha apenas com diagnostico. Fecha com diagnostico + plano consolidado oferecido + registro da decisão do usuário (executar agora, recusar, adiar ou executar subconjunto). Se o usuário aprovar execução, o agente pode transitar para atualizar_bootstrap_local e/ou corrigir_wrapper_local na mesma sessao sem exigir novo pedido do usuário.

Politica de delegacao a LLM (opcional, adiavel, nao-bloqueante)

A skill xpz-llm-delegate usa um arquivo de politica por-KB na raiz da pasta paralela para autorizar de forma duravel o envio de conteúdo desta KB a modelos externos (ver xpz-llm-delegate/SKILL.md). O nome canonico e llm-delegation-policy.json; o nome legado opencode-delegation-policy.json permanece aceito para retrocompatibilidade.

• Este item nunca e gate de setup, não entra na matriz de wrappers exigidos e não bloqueia nenhum estado de conclusao. O setup fecha normalmente sem ele.
• Ao concluir o setup, oferecer (sem cobrar) definir a politica, com pergunta em prosa e opção explicita de adiar — no setup o usuário costuma ter muito a digerir.
• Ausencia do arquivo ⇒ comportamento ask no gate (Resolve-LlmDelegateAuthorization.ps1); adiar nunca abre brecha.
• Se o usuário aceitar, gravar llm-delegation-policy.json (nome canonico) com schemaVersion, defaultExternal e entradas finas por provider/modelo conforme a escolha; nunca presumir allow-external por conta própria.
• Se a pasta ja tiver o arquivo com o nome legado opencode-delegation-policy.json, ele continua valendo; oferecer (sem cobrar) renomear para llm-delegation-policy.json. Com os dois presentes, o scripts/Resolve-LlmDelegationPolicyPath.ps1 usa o canonico e sinaliza status=both.
• No mesmo momento (tambem opcional e nao-bloqueante), oferecer gravar um snapshot de capacidade dos LLMs disponiveis na maquina com scripts/Build-LlmDelegateCapabilityManifest.ps1 -SnapshotPath <raiz-paralela>\Temp\llm-delegate-capabilities.snapshot.json, para alimentar a oferta de revisao por pares (ver 15-revisao-por-pares.md) sem re-sondar a cada uso. Capacidade != autorizacao: arquivo separado da politica, fica em Temp/ (ja ignorado pelo git), e cache re-derivavel e dica de oferta, nunca verdade do gate — o Resolve-LlmDelegateAuthorization.ps1 reavalia destino e sensibilidade sempre. Na revisao, comparar snapshotAt/sourceGeneratedAt e perguntar ao usuario se quer atualizar a sondagem ou seguir com o anotado; sem re-sondagem automatica.

PATH RESOLUTION

• Este SKILL.md fica dentro de uma subpasta de skill sob a raiz do repositório.
• Toda referência ../arquivo.md deve ser resolvida a partir da pasta deste SKILL.md, e não do diretório de trabalho corrente.
• Na prática, ../ aponta para a base metodológica compartilhada na pasta-pai desta skill.
• Quando a sessão já publicar um caminho desta skill ou de seus exemplos, usar esse caminho publicado como fonte autoritativa; não inferir caminho alternativo por heurística.
• Para examples/, resolver primeiro a pasta irmã do SKILL.md publicado na sessão. Se o SKILL.md publicado vier de fora do repositório corrente, não procurar examples/ primeiro dentro do workspace atual só porque existe uma pasta de nome parecido.
• Se o caminho publicado da skill estiver fora do workspace atual, isso não autoriza reinterpretar a origem da skill nem trocar automaticamente para um caminho "equivalente" dentro do repositório; o caminho publicado continua prevalecendo até evidência objetiva em contrário.
• Se a leitura dos examples/ publicados ainda não tiver ocorrido, a auditoria pode seguir provisoriamente com evidência local já disponível (GATE_OK, STRUCTURE_OK, parse dos wrappers, presença de seções obrigatórias e verificação de naming), deixando a classificação final contra os exemplos como etapa pendente explícita em vez de abrir exploração ampla de caminhos cedo demais.

---

TRIGGERS

Use esta skill para:

• Carga Inicial de uma KB usando repositório paralelo
• Preparar a estrutura inicial de pastas para fluxos com XPZ
• Validar se a pasta paralela da KB está pronta para sync, geração de XML ou empacotamento
• Preparar a pasta paralela da KB para uso de índice derivado em KbIntelligence
• Auditar setup de pasta paralela existente e, ao final, oferecer na mesma sessao o plano consolidado de correcoes de tudo que esta skill classificar como corrigivel nesta pasta (execução após aprovacao quando a skill exigir)
• Corrigir wrapper local defasado ou reprovado por gate, especialmente quando a evidencia vier de Test-*KbMetadataWrapper.ps1, Test-*KbIndexGate.ps1 ou Test-*KbStructure.ps1
• Atualizar wrappers de pasta paralela com histórico de uso para incorporar novos scripts previstos pela base metodologica compartilhada
• Barrar uso operacional da pasta paralela quando pwsh com PowerShell 7.4 LTS ou superior não estiver disponível
• Detectar que o AGENTS.md da pasta paralela está desatualizado em relacao ao padrão canonico atual — por exemplo, ausencia de seção ## Triagem Por Indice, lista de wrappers incompleta ou outras seções ausentes identificadas por comparacao com examples/AGENTS.md.example
• Verificar se o naming dos diretórios de container em ObjetosDaKbEmXml corresponde ao GUID real de cada objeto — especialmente Folder/, Module/ e PackagedModule/ — e propor correcao quando houver inversao ou divergencia
• Explicar a diferenca entre pasta da KB e pasta paralela da KB
• Confirmar nomes padrão das subpastas quando o usuário não informou alternativas
• Verificar consultivamente a capacidade de importação headless antes de tarefa que dependa de importação real via MSBuild, quando a pasta paralela tiver sinais de uso desse fluxo (PacotesGeradosParaImportacaoNaKbNoGenexus/ populado, wrapper local de import, ou tarefa mencionando importar, preview, MSBuild import, import_file.xml ou pacote gerado); ver seção ## CAPACIDADE DE IMPORTACAO HEADLESS

Do NOT use this skill for:

• Sincronizar XPZ específico no acervo oficial (use xpz-sync)
• Gerar ou empacotar objetos XML (use xpz-builder)
• Analisar estrutura de objeto XML individual (use xpz-reader)
• Consultar o índice derivado como etapa analitica principal (use xpz-index-triage)
• Regenerar o índice como objetivo principal da tarefa; esta skill prepara a estrutura e os wrappers locais

---

RESPONSABILIDADES

• Explicar que a pasta nativa da KB e diferente da pasta paralela da KB
• Assumir o termo principal pasta paralela da KB
• Se o caminho da pasta nativa da KB não vier no prompt, pedir esse caminho ao usuário antes de concluir o setup inicial
• Se o caminho da pasta nativa da KB vier no prompt, reutilizar esse valor sem pedir novamente
• Se o agente verificar a existência da pasta nativa da KB, declarar o resultado no handoff; se ela não existir ou não estiver acessivel, registrar o caminho informado, manter a regra de não gravacao e fechar o setup com ressalva operacional explicita
• Quando o usuário não informar nomes alternativos, assumir estas subpastas padrão:
  • scripts
  • Temp
  • XpzExportadosPelaIDE
  • ObjetosDaKbEmXml
  • KbIntelligence
  • ObjetosGeradosParaImportacaoNaKbNoGenexus
  • PacotesGeradosParaImportacaoNaKbNoGenexus
• Explicar que os nomes acima são apenas padrões sugeridos; a função de cada pasta prevalece sobre o nome literal
• Se o usuário informar nomes diferentes, registrar esse mapeamento em AGENTS.md e, quando fizer sentido para humanos, também em README.md dentro da própria pasta paralela da KB
• Registrar em AGENTS.md da pasta paralela o caminho confirmado da pasta nativa da KB
• Registrar em AGENTS.md da pasta paralela que a pasta nativa da KB e terreno proibido para gravacao por agentes, com leitura permitida apenas quando o fluxo operacional explicito realmente exigir
• Quando houver README.md local para humanos na pasta paralela, espelhar ali a identificacao da pasta nativa da KB e a regra de somente leitura em linguagem clara
• Em setup inicial padrão sem nomes alternativos, sem conflito estrutural e com pasta nativa da KB já informada, evitar exploracao ampla do motor compartilhado e dos exemplos antes de criar a estrutura base; explorar mais só se surgir bloqueio concreto
• Quando a inspecao local da pasta contradisser contexto indireto do ambiente, da sessao ou de hooks, confiar primeiro na inspecao local e seguir com verificacao curta e objetiva, sem narrativa longa de especulacao
• Explicar a função de cada subpasta
• Tratar ObjetosDaKbEmXml como snapshot oficial somente leitura para agentes
• ObjetosDaKbEmXml é o snapshot oficial da KB e agentes não o editam manualmente (editar o acervo esperando que o pacote use essa versão é anti-padrão; ver 02-regras-operacionais-e-runtime.md, anti-padrão "editar acervo esperando que o pacote pegue")
• ObjetosGeradosParaImportacaoNaKbNoGenexus é a área intermediária de trabalho anterior ao retorno oficial da KB e não atualiza diretamente o acervo oficial
• Preview ou importação bem-sucedida na IDE não atualizam, por si sós, ObjetosDaKbEmXml
• ObjetosDaKbEmXml só é atualizado depois que a KB devolve XPZ oficial e o xpz-sync materializa esse retorno
• Tratar XpzExportadosPelaIDE como pasta de entrada onde o usuário grava os .xpz exportados pela IDE
• Tratar Temp como destino preferencial para artefatos efemeros, temporarios de execução, relatórios descartaveis e copias temporarias de SQLite
• Tratar KbIntelligence como pasta do índice SQLite derivado e regeneravel, normalmente KbIntelligence\kb-intelligence.sqlite, mais relatórios de validação quando o repositório local adotar esse fluxo
• Tratar kb-source-metadata.md como metadado operacional da materialização XPZ/XML; ele deve expor last_xpz_materialization_run_at quando o fluxo oficial tiver processado um insumo da IDE
• Tratar qualquer memoria local de setup que diga ainda nao materializada, aguardando primeiro XPZ ou equivalente como estado provisório; depois da primeira materialização oficial bem-sucedida, esse estado não deve continuar sendo apresentado como atual
• Tratar KbIntelligence\kb-intelligence.sqlite como dono do metadado last_index_build_run_at na tabela metadata; esse horario deve ser igual ou posterior a last_xpz_materialization_run_at para permitir triagem ampla e geração de objetos de importação; last_index_build_run_at e a fonte autoritativa do estado de frescor do índice — qualquer decisão sobre frescor do índice deve consultar esse campo via query index-metadata, não criar campo derivado ou espelho em kb-source-metadata.md
• Além do frescor por timestamp, Test-*KbIndexGate.ps1 deve validar extractor_signature_version e extractor_signature_hash na metadata do SQLite contra o motor compartilhado (scripts/GeneXusKbIntelligenceExtractorContract.ps1 + scripts/Build-KbIntelligenceIndex.py no repositório ativo). Índice sem assinatura ou com assinatura divergente bloqueia com BLOCK: mesmo quando last_index_build_run_at >= last_xpz_materialization_run_at — regenerar o índice
• Os estados-string emitidos pelos gates de setup/índice são contrato compartilhado com a skill xpz-kb-parallel-pre-push: o estado_operacional_sugerido do Test-*KbSetupAudit.ps1 e o status/reason do Test-*KbIndexGate.ps1 (sob -AsJson) são consumidos pelos gates K8/K9 do orquestrador Invoke-XpzKbParallelPrePushPhase1.ps1 daquela skill. Renomear esses literais aqui é breaking para a rotina pré-push de pasta paralela — alterar os dois lados juntos. scripts/Test-XpzKbIndexGate.ps1 faz parte do setup-contract.manifest.json justamente por ser consumido por essa via
• Regeneracao do índice via Rebuild-*KbIntelligenceIndex.ps1 (motor scripts/Build-KbIntelligenceIndex.ps1) exige Python 3.x utilizavel no PATH (scripts/GeneXusPythonPrerequisite.ps1; stub da Microsoft Store em WindowsApps não conta). Ausencia bloqueia o refresh com exit 8 e mensagem PREREQUISITO AUSENTE — rigor: sync normal não terminou; a materialização XPZ/XML em ObjetosDaKbEmXml pode já ter concluido, mas isso não equivale a sucesso do fluxo oficial nem autoriza triagem ampla sem índice. Não tratar como falha do pacote exportado; instalar Python 3.x e rerodar o rebuild (Rebuild-*KbIntelligenceIndex.ps1). O molde Update-KbFromXpz.example.ps1 propaga essa mensagem quando o encadeamento de rebuild falhar no mesmo pwsh. Ver README.md, 02-regras-operacionais-e-runtime.md e xpz-sync da base compartilhada
• Tratar kb-source-metadata.md e a saida de -Query index-metadata do wrapper local como fontes autoritativas dos timestamps operacionais de materialização e índice; AGENTS.md e README.md locais servem como memoria auxiliar humana (wrappers, fluxos, pacotes de referencia) e não devem gravar timestamps literais de last_xpz_materialization_run_at ou last_index_build_run_at — apenas ponteiros para as fontes autoritativas e para a linha declarativo/timestamps em Test-*KbSetupAudit.ps1
• Tratar kb-source-metadata.md por autoridade de campo, não por dono único do arquivo:
  • identidade estavel da KB (Source/kb (GUID), Source/username, Source/UNCPath, Source/Version/guid, Source/Version/name): autoridade primaria do setup/resolvedor da KB nativa local; autoridade secundaria do XPZ somente quando o pacote vier completo e coerente com a KB local
  • KMW (MajorVersion, MinorVersion, Build): autoridade primaria do XPZ real ou template real comparavel; setup não deve inventar esses valores sem evidencia
  • materialização (last_xpz_materialization_run_at, source_xpz, source_refresh_status): autoridade do fluxo xpz-sync
  • auditoria de setup (last_setup_audit_run_at, setup_contract_signature_version, setup_contract_signature_hash): autoridade desta skill, nos estados canonicos permitidos
  • environments GeneXus (deployment_environment_name, deployment_hosting_kind, kb_environment_count, kb_environment_names, kb_environment_output_dirs, kb_environment_web_dirs): autoridade declarada pelo usuário (nomes exatos como na IDE e diretórios de output confirmados por environment) via scripts/Set-XpzKbSourceMetadataDeployment.ps1 (wrapper local Set-*KbSourceMetadataDeployment.ps1); obrigatório -KbEnvironmentNames, -KbEnvironmentOutputDirs e validação MSBuild (SetActiveEnvironment headless sobre a lista informada); kb_environment_web_dirs pode ser derivado de -KbNativePath + output dir + web, sem scan; scan/inventario automático por pastas da KB nativa (-InventoryFromKbNativePath, -InventoryFromGeneXusMsBuild) removido; -SkipEnvironmentNamesMsBuildValidation só quando sondagem MSBuild indisponivel por infraestrutura; build/import/diagnostico de .cs só leem metadata gravado
• Tratar deployment_environment_name como identificador MSBuild aceito por SetActiveEnvironment (ex.: NETPostgreSQL), não nome descritivo de GetEnvironmentProperty -Name Name
• Tratar deployment_hosting_kind como um dos valores do registro-fonte-única GeneXusKbHostingKindSupport.ps1 (dotnet-core-self-host, dotnet-framework-iis, java-tomcat), validado em runtime contra o registro (não mais por [ValidateSet]; a escrita em Set-XpzKbSourceMetadataDeployment.ps1 e o diagnóstico de consistência rejeitam valor fora do registro com mensagem canônica). A partir da Fase 3, o suporte é PER-EIXO (deployBinSupportState/sourceSupportState/runtimeSupportState); cada consumidor discrimina pelo predicado do seu eixo (runsDeployBinEngine/runsSourceEngine/runsRuntimeEngine), não pelo alias legado runsFreshnessEngine. Para os hosting kinds .NET, o gate pos-import olha publicacao em web\bin (DLL de objeto + config), não GxNetCoreStartup.dll sozinha (xpz-msbuild-build, exit 49). java-tomcat tem Eixo A (deploy-bin) com motor (co-gate por conjunto de artefatos, alvo externo WEB-INF\classes) — fresh/stale/no-evidence/unexpected-publication/unknown; os Eixos B/C (.cs/.java e runtime) seguem sem motor (recognized-no-engine, Pós-v1) e pulam (skipped-hosting-unsupported/exit 0) — skip ≠ deploy validado
• Gravar, para env Java/Tomcat, os campos de metadata dedicados do alvo do co-gate (Eixo A): kb_environment_servlet_dirs (= alvo externo que termina em WEB-INF\classes), kb_environment_app_package (pacote da app, ex.: com\<kb>) e kb_environment_servlet_flavor (jakarta|javax). São AUDIT_REQUIRED (autoria declarada pelo usuário; model.ini/GeneratorType nunca autoridade). A Fase 5 Java/Tomcat (EBTECH, 2026-07-07) mediu Jakarta e também um environment GeneXus JAVA_EE/Gradle javaEE com sinais reais javax em Tomcat 11/JDK 21/Servlet 6; Java EE clássico puro Tomcat 8/9 + JDK 8 segue não medido. A mesma Fase 5 mostrou que SERVLET_DIR do model.ini é evidência útil só após resolver o environment/bloco correto; quando houver Gradle, confrontar também <output>\web\gradle.properties (TOMCAT_WEBAPP_PATH, TOMCAT_STATIC_PATH) e aceitar o alvo apenas depois de auditar WEB-INF\classes, a sentinela irmã WEB-INF\lib\GeneXus.jar e a compatibilidade do pacote da app declarado. Divergência entre model.ini e gradle.properties deve virar auditoria/decisão humana, não escrita cega. Resolve-XpzJavaTomcatMetadataSuggestion.ps1 é assistente read-only para produzir candidatos e evidência; a gravação continua opt-in via Set-XpzKbSourceMetadataDeployment.ps1/wrapper local, com -KbEnvironmentServletDirs e -KbEnvironmentAppPackage obrigatoriamente completos para todos os environments declarados quando usados. Test-XpzKbMetadataWrapper.ps1 audita a exposição desses campos pelo wrapper e Test-XpzKbDeploymentMetadata.ps1 valida plausibilidade/forma. Sem esses campos, o co-gate Java resolve config-error → unknown (fail-safe), nunca fresh; com eles, o motor usa kb_environment_app_package como allowlist e a falta de artefatos sob o pacote aparece pela classificação do co-gate, não por validação de metadata. Auto-população sem confirmação continua fora de escopo.
• Tratar kb_environment_post_build_event_hashes (fingerprints SHA-256 dos eventos pos-build conhecidos por environment, encoding plano env=h1,h2; env2=h3) como autoridade desta skill via scripts/Register-GeneXusKbPostBuildEvents.ps1: registra a partir do JSON de um build (stdoutSignals.postBuildEvents), filtra saídas inertes estritamente reconhecidas (REM comentado, duração TimeSpan válida ou data civil válida), grava o campo plano e a secao-espelho legivel ## Eventos pos-build registrados (linhas cruas, só para auditoria humana — o build le os hashes, não o espelho). O fingerprint normaliza apenas variações inocuas previstas pelo motor, como tempo: <n> ms na saída Verify-GxJs com invalidos: 0; os demais campos continuam fazendo parte do hash. Ação sensivel — registrar desarma o rebaixamento por evento pos-build daquele environment: exige confirmacao (frase exata interativa ou -ConfirmRegistration em modo agente, após o usuário aprovar). O build (xpz-msbuild-build) compara os eventos observados por fingerprint: registrado = esperado (não rebaixa); não registrado = rebaixa por cautela; sem registro, rede de seguranca reconhece player de som como benigno
• Tratar kb_environment_count = 1 como permissao para omitir -EnvironmentName nos wrappers de build quando o environment ativo GeneXus for o único da KB; kb_environment_count > 1 exige -EnvironmentName explicito ou deployment_environment_name preenchido antes de validação pós-import (xpz-msbuild-build)
• Em modo_atualizacao ou quando campos de environment/deploy/output estiverem ausentes ou suspeitos: perguntar ao usuário (1) quais são os environments GeneXus desta KB — nomes exatos como na IDE / SetActiveEnvironment; (2) qual e o environment de deploy/validacao headless; (3) qual diretório de output corresponde a cada environment (ex.: NETPostgreSQL=NETPostgreSQL, .Net Environment=NETFrameworkPostgreSQL); executar Set-XpzKbSourceMetadataDeployment.ps1 (ou wrapper local) com -DeploymentEnvironmentName, -DeploymentHostingKind, -KbEnvironmentNames, -KbEnvironmentOutputDirs, -KbNativePath e -InventoryWorkingDirectory; validação MSBuild e obrigatória salvo sondagem indisponivel (-SkipEnvironmentNamesMsBuildValidation com pendencia explicita no handoff). kb_environment_web_dirs pode ser derivado pelo motor quando -KbNativePath estiver presente; scan automático de pastas da KB nativa e proibido.
• Tratar divergencia de Source/kb (GUID) como bloqueio de seguranca: se um pacote, template ou XPZ trouxer GUID de KB preenchido e diferente da KB nativa local registrada/resolvida para a pasta paralela, o agente não deve trocar o Source para normalizar o pacote nem prosseguir com import headless; deve bloquear a automacao e encaminhar o usuário para importação manual pela IDE
• Quando a pasta paralela já tiver gerado e importado com sucesso pacotes import_file.xml, registrar em AGENTS.md local uma seção opcional ## Pacote de referencia conhecido listando o caminho de pelo menos um pacote real comparavel para cada natureza de pacote praticada nesta pasta (full, delta cirurgico, migracao). Esse caminho serve como candidato default para -TemplatePackagePath do motor compartilhado scripts/New-XpzImportPackage.ps1 em rodadas futuras, conforme a regra de comparabilidade documentada em xpz-builder/SKILL.md. Quando essa seção não existir ou não apontar pacote comparavel ao caso corrente, o agente que invocar o motor deve omitir -TemplatePackagePath e aceitar o envelope mínimo (warning envelope-minimo) explicitamente. Manter essa seção como opcional: a pasta paralela pode operar sem ela enquanto o usuário não tiver pacote comparavel para citar
• Tratar last_setup_audit_run_at em kb-source-metadata.md como timestamp da última execução de setup ou auditoria de setup concluida com sucesso nesta pasta paralela; tratar setup_contract_signature_version e setup_contract_signature_hash como a assinatura de contrato de xpz-kb-parallel-setup validada nessa auditoria. Gravar esses campos imediatamente após declarar qualquer estado canonico de conclusao bem-sucedido (pronto_para_primeira_materializacao, materializado_e_indice_validado, wrappers_atualizados); não gravar quando a conclusao for bootstrap_incompleto, auditoria_de_empacotamento_pendente ou atualizacao_metodologica_pendente, pois esses estados indicam conclusao parcial e não garantem que a próxima invocacao pode confiar no setup como integro. Esses campos são diferentes dos timestamps operacionais de materialização e índice: last_xpz_materialization_run_at pertence ao fluxo xpz-sync; last_index_build_run_at pertence ao SQLite do KbIntelligence; last_setup_audit_run_at e setup_contract_signature_* pertencem somente a auditoria de setup bem-sucedida.
• Explicar que o fluxo oficial de materialização XPZ/XML deve chamar a regeneracao/validacao do índice derivado compulsoriamente após atualizar ObjetosDaKbEmXml
• Explicar que, após processamento bem-sucedido, um .xpz em XpzExportadosPelaIDE pode ser renomeado para processado_<nome-original>.xpz
• Tratar ObjetosGeradosParaImportacaoNaKbNoGenexus como area de trabalho para XMLs temporarios destinados a importação manual na IDE
• Tratar PacotesGeradosParaImportacaoNaKbNoGenexus como area de saida para import_file.xml e, quando aplicavel, XPZ
• Tratar ObjetosGeradosParaImportacaoNaKbNoGenexus e PacotesGeradosParaImportacaoNaKbNoGenexus como areas gerenciadas por agente, não como deposito geral do usuário; XML de referencia, exemplo ou template deixado na frente ativa deve ser bloqueio de empacotamento ate ser removido ou tratado por caminho explicito fora da frente
• Por padrão, ObjetosGeradosParaImportacaoNaKbNoGenexus e PacotesGeradosParaImportacaoNaKbNoGenexus não precisam ser versionadas em Git; se houver duvida sobre rastrear ou ignorar seu conteúdo, tratar isso como decisão de politica do repositório e pedir aprovacao explicita
• Exigir que cada frente ativa em ObjetosGeradosParaImportacaoNaKbNoGenexus use sua própria subpasta NomeCurto_GUID_YYYYMMDD
• Explicar que NomeCurto_GUID_YYYYMMDD combina nome curto, GUID criado na abertura da frente e data de criacao da frente; YYYYMMDD representa a data de criacao da frente, não a data do pacote
• Explicar que a subpasta NomeCurto_GUID_YYYYMMDD e a unidade ativa da frente
• Exigir reuso da mesma subpasta quando a frente já existir e estiver sendo retomada
• Exigir que PacotesGeradosParaImportacaoNaKbNoGenexus permaneça plano, sem subpastas por frente
• Explicar que novos XPZ completos podem ser usados a qualquer momento para reatualizar ObjetosDaKbEmXml
• Quando acionado para revisar naming de ObjetosDaKbEmXml em pasta paralela existente, ler pelo menos um XML de cada diretório de container (Folder/, Module/, PackagedModule/) e verificar o Object/@type real antes de qualquer conclusao sobre inversao ou conformidade
• Distinguir Carga Inicial, atualizacao incremental e empacotamento local
• Em pasta com PacotesGeradosParaImportacaoNaKbNoGenexus, auditar separadamente a aderencia do fluxo de empacotamento local; sync/indice OK não autorizam concluir sozinho que "está tudo certo"
• Explicar que materializar um XPZ completo da IDE inclui quebrar o full.xml em XMLs individuais por objeto
• Explicar que o acervo materializado deve ser organizado em subpastas por tipo amigavel de objeto GeneXus
• Explicar que os XMLs materializados devem usar nomes amigaveis dos objetos, não GUID como nome principal
• Explicar que guid, parentGuid, parentType e moduleGuid são metadados de apoio para consistencia e rastreabilidade, não o eixo principal de organizacao
• Explicar que o índice em KbIntelligence só pode ser gerado depois que ObjetosDaKbEmXml existir e contiver o snapshot oficial materializado
• Explicar que KbIntelligence não substitui ObjetosDaKbEmXml; ele e uma camada derivada para triagem e deve ser regeneravel a partir do snapshot oficial
• Explicar que, se last_index_build_run_at estiver ausente ou anterior a last_xpz_materialization_run_at, o agente não deve pesquisar o acervo em massa nem gerar objetos para importação; deve tratar isso como exceção operacional e oferecer a regeneracao/validacao do índice antes de seguir
• Prever wrappers locais .ps1 na pasta scripts quando a pasta paralela da KB precisar reconstruir o fluxo operacional local sobre o motor compartilhado; distinguir: scripts com parâmetros estáticos da KB (caminhos fixos, nome da KB, GUIDs) merecem wrapper local; scripts com parâmetros totalmente dinâmicos por execução (ex: Watch-GeneXusMsBuildLog.ps1, cujo -Pid e -LogPath variam a cada build) são chamados diretamente do motor pelo caminho absoluto, sem wrapper local
• Exigir wrapper local Test-*KbPowerShellRuntime.ps1 como primeiro gate de qualquer uso operacional da pasta paralela; ele deve delegar ao motor compartilhado scripts\Test-XpzPowerShellRuntime.ps1, exigir pwsh com PowerShell 7.4 LTS ou superior e bloquear o prosseguimento quando retornar BLOCK: ou estiver ausente
• Quando a pasta paralela da KB também for usada para gerar XMLs locais e pacotes de importação, prever wrapper local consultivo para gate de sanidade do Source antes do empacotamento
• Quando a pasta paralela da KB for inicializada do zero para operar com fluxo oficial de materialização XPZ/XML, tratar a camada mínima de wrappers locais em scripts como parte do bootstrap técnico esperado, não como pendencia para a etapa seguinte
• Não declarar setup inicial concluido, estrutura pronta ou equivalente final se a pasta ainda não tiver a camada mínima de wrappers locais necessária para materialização oficial e, quando adotado, para KbIntelligence
• Se a pasta paralela já estiver versionada em Git, tratar .gitignore na raiz e .gitkeep nas subpastas estruturais vazias como parte esperada do setup inicial padrão
• Se a pasta paralela ainda não estiver versionada em Git, o agente pode oferecer inicializar versionamento Git local como passo opcional de apoio; a decisão pertence ao usuário
• Não executar git init por conta própria no setup inicial
• Ao criar .gitignore — independente de o repositório já estar versionado ou não — cobrir obrigatoriamente: Temp, KbIntelligence (apenas kb-intelligence.sqlite e kb-intelligence-validation.json), ObjetosGeradosParaImportacaoNaKbNoGenexus, PacotesGeradosParaImportacaoNaKbNoGenexus e XpzExportadosPelaIDE; ObjetosDaKbEmXml não deve ser ignorado pelo .gitignore pois e o acervo oficial versionavel
• Toda pasta coberta no .gitignore com o padrão pasta/* e !pasta/.gitkeep deve ter o arquivo .gitkeep correspondente criado no mesmo passo em que o .gitignore e gravado; não criar .gitignore que referencia .gitkeep sem criar o arquivo físico
• Se o usuário aceitar versionamento Git local e o ambiente não tiver Git funcional, o agente pode oferecer instalar ou orientar a instalacao antes de prosseguir com o bootstrap Git
• Alterar .gitignore, politica de versionamento ou escopo de arquivos rastreados para viabilizar git add/commit e decisão de politica do repositório; o agente pode diagnosticar e propor opções, mas não deve mudar essa politica automaticamente só para concluir o fechamento
• Reutilizar o fluxo oficial previsto nas skills e no motor compartilhado antes de considerar qualquer script novo
• Gerar kb-source-metadata.md inicial em formato compativel com o motor compartilhado, preservando desde o setup o campo nominal last_xpz_materialization_run_at
• Quando o caminho da KB nativa local estiver confirmado no setup inicial, resolver a identidade estavel por scripts\Resolve-GeneXusKbIdentity.ps1 antes de declarar o metadata apto e gravar kb-source-metadata.md já com Source/kb (GUID), Source/username, Source/UNCPath, Source/Version/guid e Source/Version/name preenchidos quando a resolucao passar. Se a resolucao falhar, não declarar estado limpo de metadata; registrar a pendencia e orientar a correcao em vez de depender de XPZ futuro com Source preenchido.
• Não salvar memoria operacional fora da própria pasta paralela da KB sem autorizacao explicita do usuário; AGENTS.md, README.md e arquivos operacionais locais são a camada preferencial de memoria do setup
• Ao concluir o setup inicial, declarar explicitamente que a pasta paralela está pronta, mas ObjetosDaKbEmXml ainda não foi materializada
• Quando o setup inicial tiver registrado memoria local provisoria de que ObjetosDaKbEmXml ainda não foi materializada, exigir refresh dessa memoria local depois da primeira materialização oficial bem-sucedida, para evitar handoff com estado desatualizado
• Em modo_criacao, antes de iniciar qualquer escrita, verificar se o prompt de entrada já declara explicitamente a preferencia por A) ou B); se sim, prosseguir sem perguntar; se não, perguntar ao usuário qual caminho prefere antes de comecar qualquer trabalho — a pergunta deve ser feita no inicio da skill, não após o setup estar concluido; agente que cria toda a estrutura e só entao pergunta A/B obriga o usuário a aguardar o setup inteiro para responder algo que podia ser respondido antes de qualquer escrita
• Ao concluir o setup inicial, os dois próximos passos são:
  • A) o usuário exporta o .xpz full pela IDE do GeneXus para XpzExportadosPelaIDE e o agente materializa os XMLs depois
  • B) o agente tenta gerar o .xpz full a partir da pasta nativa da KB, grava esse .xpz em XpzExportadosPelaIDE e depois materializa os XMLs
• Ao apresentar A) e B), dizer explicitamente que A) e o caminho preferencial e normalmente mais rápido, enquanto B) tende a demorar mais por depender da trilha via MSBuild
• Ao orientar o caminho A), preferir descrição funcional estavel como export full da KB pela IDE em vez de depender de rotulos exatos de menu, tela ou botao do GeneXus como se fossem universais; se citar caminho de menu, apresentá-lo depois da instrucao principal e marcado explicitamente como exemplo opcional de navegacao, nunca como passo normativo principal
• Se o usuário escolher B), encaminhar a geração do .xpz full pela skill xpz-msbuild-import-export em vez de improvisar exportação fora dessa trilha
• Ao concluir exportação via B), verificar em kb-source-metadata.md se o campo kb (GUID) na seção ## Source foi populado com um GUID real e coerente com a KB nativa local. Exportacoes full geradas via MSBuild ou IDE podem não conter Source completo; isso deve ser tratado como metadata incompleto a resolver pela identidade local aprovada, não como motivo automático para pedir reexport. Se o pacote trouxer GUID preenchido de outra KB, bloquear import headless e orientar importação manual pela IDE
• Ao concluir exportação via B), quando o export.json emitido por Invoke-GeneXusXpzExport.ps1 vier com postProcessingFailed=true mas o msbuild.stdout.log contiver Export Sucesso e __EXPORTED_FILE__=<caminho> e o arquivo XPZ existir no caminho indicado, NÃO classificar a rodada como falha operacional nem reiniciar a exportação; tratar como XPZ gerado com diagnostico degradado, declarar o marco XPZ gerado no handoff e prosseguir para a materialização; classificação formal e governanca do sub-estado exportacao headless concluida e XPZ gerado (falha no pos-processamento do wrapper) pertencem a xpz-msbuild-import-export — esta skill apenas roteia para la quando houver duvida
• No handoff após exportação via B) com XPZ gerado, reproduzir no texto ao usuário os totais reais de packageInventory (totalObjects, totalAttributes, objectsByType, systemObjectsPresent, attributesTopLevelUnreconciled e inventoryWarnings quando existirem), exportErrors/invalidTypesRejected/knownStdOutNoise/exitCode/msBuildCategoryBBlocked no top-level do export.json quando existirem, e o operationalSubState; com exitCode=48 ou sub-estado exportação parcial com errors do MSBuild — artefato não confiável, PARAR — o XPZ não e entrega limpa; abrir package-inventory.json (via nominalInventoryAt, packageInventoryPath ou artifacts.PackageInventoryPath) sempre que extrasCount > 0, attributesTopLevelUnreconciled=true, ou systemObjectsPresent não vazio, e reproduzir a lista nominal completa por bloco — atributos top-level por nome somente quando attributesTopLevelUnreconciled=true; nunca resumir a rodada com a contagem de entradas de -ObjectList — governanca completa em xpz-msbuild-import-export (seção inventario após export seletivo)
• Em diagnostico degradado de export/import MSBuild, quando existir executionEvidence.msBuildExitCode, trata-lo como fonte canonica do exit bruto do MSBuild; msBuildExitCode top-level e compatibilidade transitoria e não deve substituir a leitura canonica nem a classificação da skill xpz-msbuild-import-export
• Quando o usuário precisar inspecionar uma propriedade da KB, Version, Environment, Generator, DataStore ou objeto específico sem abrir a IDE, o script Get-GeneXusKbProperty.ps1 do motor compartilhado está disponível via xpz-msbuild-import-export; seu uso e pontual e sob demanda — não faz parte de nenhuma etapa obrigatória do setup

---

MAPEAMENTO INTENCAO -> FUNÇÃO DA PASTA

• Se a intencao for consultar o acervo materializado da KB:
  • usar a pasta com função de acervo materializado
  • essa pasta recebe XMLs individuais extraidos do XPZ exportado pela IDE
  • essa pasta pode usar subpastas por tipo amigavel de objeto GeneXus
• Se a intencao for consultar relacoes, impacto técnico ou trilha funcional curta por índice derivado:
  • usar a pasta KbIntelligence como destino do SQLite derivado e dos relatórios de validação
  • usar wrappers locais em scripts para consultar ou regenerar o índice
  • manter ObjetosDaKbEmXml como fonte normativa e origem de regeneracao do índice
• Se a intencao for gerar XML novo ou copia alterada para futura importação na IDE:
  • usar a pasta com função de geração para importação
  • essa pasta recebe apenas XMLs novos ou copias alteradas geradas pelo agente
  • cada frente ativa deve usar sua própria subpasta NomeCurto_GUID_YYYYMMDD
• Se a intencao for guardar XPZ exportado pela IDE:
  • usar a pasta com função de entrada de XPZ
  • essa pasta não e acervo materializado nem area de geração de XML
• Se a intencao for guardar pacote final de importação:
  • usar a pasta com função de saida de pacotes
  • essa pasta recebe import_file.xml e, quando aplicavel, XPZ

---

REGRAS DE NAMING

• Para acervo materializado, preferir subpastas por tipo amigavel de objeto GeneXus, por exemplo Transaction, Procedure, WebPanel
• Para containers GeneXus, adotar a convencao canonica derivada da FabricaBrasil: Folder/ para objetos com Object/@type="00000000-0000-0000-0000-000000000008" (containers criados pelo usuário — "Pastas") e Module/ para objetos com Object/@type="00000000-0000-0000-0000-000000000006" (containers de sistema: Main Programs, ToBeDefined)
• O nome do subdiretorio em ObjetosDaKbEmXml NÃO e indicador confiavel do tipo GeneXus entre KBs; a fonte autoritativa e sempre Object/@type no XML do objeto
• Para acervo materializado, preferir nome amigavel do objeto como nome do XML, por exemplo Cliente.xml, GeraBoleto.xml
• Não usar GUID como nome principal de pasta ou arquivo do acervo materializado
• Se houver colisao rara de nome, o GUID pode aparecer apenas como apoio de desambiguacao, nunca como eixo principal da organizacao
• GUID, parentGuid, parentType e moduleGuid servem como metadados de apoio, não como estrutura principal de saida
• Para frente ativa em ObjetosGeradosParaImportacaoNaKbNoGenexus, usar a subpasta NomeCurto_GUID_YYYYMMDD
• Para pacote final em PacotesGeradosParaImportacaoNaKbNoGenexus, usar o formato NomeCurto_GUID_YYYYMMDD_nn.import_file.xml
• nn representa apenas a rodada curta do pacote naquela frente; não representa versão semantica
• no pacote final, o vinculo com a frente existe apenas pelo prefixo NomeCurto_GUID_YYYYMMDD somado ao nn

---

WRAPPERS LOCAIS ESPERADOS

Matriz de exigencia por wrapper

Referencia rápida para decidir o peso operacional da ausencia de cada wrapper. As regras detalhadas de classificação (AUSENTE / EQUIVALENTE / CUSTOMIZADO) e os critérios de evidencia permanecem em 8.a e 8.g3; esta tabela e leitura rápida, não substituto.

Wrapper	Obrigatório quando	Ausencia impede
Test-*KbPowerShellRuntime.ps1	sempre (primeiro gate de uso operacional)	qualquer uso operacional da pasta paralela
Test-*KbObjetosDaKbNaming.ps1	ObjetosDaKbEmXml materializado	wrappers_atualizados e materializado_e_indice_validado limpos
Test-*KbSetupFreshness.ps1	sempre (invocacao pelo gatilho global)	fast path da PRE-CONDICAO — ausente forca auditoria completa a cada invocacao do gatilho
Set-*KbSetupAuditTimestamp.ps1	recomendado quando last_setup_audit_run_at ou setup_contract_signature_* estiver ausente, invalido ou defasado após auditoria bem-sucedida	nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente ou a edicao manual seguir o passo 34
Update-*KbFromXpz.ps1	sempre (fluxo oficial de materialização)	pronto_para_primeira_materializacao
Test-*KbFullSnapshot.ps1	sempre (fluxo oficial de materialização)	pronto_para_primeira_materializacao
Query-*KbIntelligence.ps1	KbIntelligence adotado	wrappers_atualizados
Rebuild-*KbIntelligenceIndex.ps1	KbIntelligence adotado	wrappers_atualizados
Test-*KbIndexGate.ps1	KbIntelligence adotado	wrappers_atualizados
Get-*KbMetadata.ps1	KbIntelligence adotado	wrappers_atualizados
Resolve-*KbIdentity.ps1	esperado no setup inicial/auditoria quando a pasta tem KB nativa local confirmada e precisa preencher ou conferir identidade estavel; recomendado nas demais reconciliacoes aprovadas em que o XPZ veio com Source vazio ou incompleto	metadata apto para empacotamento quando a identidade estavel estiver ausente, incompleta ou divergente
Test-*KbMetadataWrapper.ps1	KbIntelligence adotado	wrappers_atualizados
Test-*KbStructure.ps1	KbIntelligence adotado	wrappers_atualizados
Test-*KbSetupAudit.ps1	KbIntelligence adotado	wrappers_atualizados
Test-*KbSourceSanity.ps1	empacotamento local adotado	auditoria_de_empacotamento_pendente
Test-*KbPackageCollision.ps1	empacotamento local adotado	auditoria_de_empacotamento_pendente
New-*KbFront.ps1	recomendado quando agentes abrem frentes locais com frequência e precisam evitar comandos PowerShell compostos	nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente ou os passos atomicos forem executados separadamente
Get-*KbLastUpdate.ps1	recomendado quando agentes atualizam lastUpdate em XMLs locais com frequência e precisam evitar comandos PowerShell compostos	nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente ou o timestamp puder ser obtido por comando atômico
New-*KbImportPackage.ps1	recomendado quando o empacotamento local for recorrente e a KB precisar de comando curto/allowlist	nenhum estado, enquanto o motor compartilhado puder ser chamado diretamente
Notify-TaskComplete.ps1	opcional	nenhum estado

• Além do gate obrigatório Test-*KbPowerShellRuntime.ps1, a pasta scripts deve prever pelo menos dois wrappers locais quando a pasta paralela da KB operar com fluxo oficial de materialização XML sobre o motor compartilhado:
  • wrapper de atualizacao diaria a partir de .xpz, XML exportado ou pasta contendo o XML do pacote
  • wrapper de conferencia full que reutiliza o wrapper diario em modo VerifyOnly + FullSnapshot
• Quando a pasta paralela precisar reconciliar identidade estavel da KB nativa local porque o XPZ exportado veio com Source vazio ou incompleto, recomendar wrapper local fino Resolve-*KbIdentity.ps1:
  • delega para scripts\Resolve-GeneXusKbIdentity.ps1 da base compartilhada
  • opera em modo somente leitura sobre model.ini, knowledgebase.connection e banco interno da KB
  • retorna kbGuid, kbName, versionGuid, versionName, UNCPath e username para apoiar preenchimento aprovado de kb-source-metadata.md
  • quando chamado com opção local equivalente a -UpdateMetadata, delega para scripts\Update-XpzKbSourceMetadataIdentity.ps1, preenche campos ausentes de identidade estavel e bloqueia divergencias não vazias salvo aprovacao explicita para sobrescrita
  • não substitui o Get-*KbMetadata.ps1: resolve identidade a partir da KB nativa; Get-*KbMetadata.ps1 le o metadata já gravado
• Quando a pasta paralela da KB adotar KbIntelligence, a pasta scripts também deve prever wrappers locais finos para:
  • consulta do índice derivado em KbIntelligence\kb-intelligence.sqlite
  • regeneracao e validação do índice a partir de ObjetosDaKbEmXml
  • execução do gate de frescor (Test-*KbIndexGate.ps1): chama o wrapper de consulta local com -Query index-metadata, le kb-source-metadata.md, compara timestamps e retorna GATE_OK ou lanca BLOCK: <motivo>; depende de Query-*KbIntelligence.ps1 na mesma pasta; deve ser o único ponto de execução do gate de frescor
  • leitura de campos chave de kb-source-metadata.md (Get-*KbMetadata.ps1): elimina o padrão recorrente de Select-String + regex inline nos chamadores; expoe ao menos last_xpz_materialization_run_at, kb_name e source_guid
    • contrato semantico canonico dos tres campos:
      • last_xpz_materialization_run_at: campo de topo ou frontmatter de kb-source-metadata.md
      • kb_name: campo name da tabela na seção ## Source/Version (nome da KB na IDE)
      • source_guid: campo kb (GUID) da tabela na seção ## Source — GUID da KB, não o GUID da versão em ## Source/Version; implementacoes que lerem source_guid de ## Source/Version serao semanticamente incorretas mesmo com parse valido
  • validação do contrato funcional de metadata (Test-*KbMetadataWrapper.ps1): chama o motor compartilhado Test-XpzKbMetadataWrapper.ps1, compara o que Get-*KbMetadata.ps1 expoe contra kb-source-metadata.md e retorna METADATA_WRAPPER_OK, METADATA_WRAPPER_INCOMPLETE, PENDENTE_DE_DADOS ou BLOCK: ...
  • validação de plausibilidade semantica de environment/deploy/output (Test-XpzKbDeploymentMetadata.ps1, consolidada em Test-*KbSetupAudit.ps1 como metadata/deploy): rejeita metadata legado (tipico de scan por pastas web\), inconsistencias de contagem e mapeamento de output/web ausente ou divergente; não substitui pergunta ao usuário nem validação MSBuild de nomes declarados
  • auditoria de naming de ObjetosDaKbEmXml (Test-*KbObjetosDaKbNaming.ps1): chama o motor compartilhado Test-XpzObjetosDaKbNaming.ps1, cobre todos os diretórios imediatos do snapshot, extrai o tipo real por raiz Attribute ou Object/@type, compara com o catalogo efetivo (gx-object-type-catalog.json + scripts/gx-object-type-catalog.override.json quando existir) e retorna NAMING_OK, NAMING_DIVERGENT ou NAMING_INDETERMINADO; não renomeia diretórios
  • verificacao de estrutura da pasta paralela (Test-*KbStructure.ps1): relatório de presenca/ausencia de pastas, scripts e artefatos esperados; retorna STRUCTURE_OK ou lista componentes ausentes; usado no setup e em diagnostico antes de qualquer operacao
  • gate de runtime PowerShell (Test-*KbPowerShellRuntime.ps1): chama o motor compartilhado Test-XpzPowerShellRuntime.ps1, verifica existência de pwsh com PowerShell 7.4 LTS ou superior e bloqueia qualquer uso operacional da pasta paralela se retornar BLOCK:; deve ser o primeiro wrapper executado em setup, auditoria, frescor, sync, índice ou empacotamento
  • auditoria agregada de setup (Test-*KbSetupAudit.ps1): chama o motor compartilhado Test-XpzSetupAudit.ps1, consolida evidencias deterministicas de powershell/runtime, sync/materializacao, naming/objetos-da-kb, indice/gate, indice/semantica, metadata wrapper, metadata/deploy, empacotamento local, declarativo/timestamps, wrappers/inventario e estado_operacional_sugerido; deve orquestrar os gates específicos, nunca substitui-los como evidencia primaria; quando -PowerShellRuntimeTestPath não for informado ao motor compartilhado, ele varre scripts/Test-*KbPowerShellRuntime.ps1, usa o wrapper único detectado e, se nenhum existir, emite powershell/runtime.detecao=missing, powershell/runtime.wrapper_sugerido e powershell/runtime.molde sem criar arquivo automaticamente; quando existir e a intencao operacional for auditar_setup, o agente deve executa-lo e usar sua saida consolidada como veiculo de handoff — as dimensoes do wrapper substituem a sintese manual dessas mesmas dimensoes, mas não substituem a evidencia dos gates específicos que as fundamentam
• Quando a pasta paralela da KB operar com ObjetosGeradosParaImportacaoNaKbNoGenexus e PacotesGeradosParaImportacaoNaKbNoGenexus, recomendar também wrapper local fino para gate de Source, por exemplo Test-*KbSourceSanity.ps1:
  • recebe um XML específico em -InputPath; -Path, quando aceito, e alias de compatibilidade
  • delega para scripts\Test-GeneXusSourceSanity.ps1 da base compartilhada
  • não repassa -AsJson ao motor compartilhado: Test-GeneXusSourceSanity.ps1 já emite JSON por padrão e NÃO aceita -AsJson (trava confirmada por Test-XpzParameterNamingContract.ps1); o motor também espera um arquivo, não uma pasta — se o wrapper local precisar varrer varios XML ou montar JSON próprio, faz isso no wrapper sem propagar a flag para baixo
  • retorna JSON por padrão no stdout, suficiente para distinguir xmlWellFormed, sourceSanityStatus e probablyImportable
  • bloqueia empacotamento local quando encontrar sourceSanityStatus=fail
  • em warn, devolve a lista de warnings e exige revisao conservadora antes do pacote
• Quando a pasta paralela da KB operar com empacotamento local em PacotesGeradosParaImportacaoNaKbNoGenexus, recomendar também wrapper local fino para gate de colisao de pacote, por exemplo Test-*KbPackageCollision.ps1:
  • recebe FrontPrefix, NN e OutputDir, ou PackagePath; -Path/-InputPath, quando aceitos, são alias de compatibilidade para PackagePath
  • delega para scripts\Test-XpzPackageCollision.ps1 da base compartilhada
  • retorna JSON com status=ok, reason=COLLISION_OK e exit 0 quando a rodada pretendida ainda não existe
  • retorna JSON com status=bloqueado, reason=PACKAGE_ROUND_COLLISION, blockingReasons, nextFreeNN, nextFreeRound e exit 20 quando a rodada nn já existir para o mesmo prefixo de frente
  • deve ser o único ponto local para decidir se o pacote pode ser gravado ou se a frente deve bloquear por colisao
• Quando agentes abrirem frentes locais com frequência em ObjetosGeradosParaImportacaoNaKbNoGenexus, recomendar wrapper local fino para abertura de frente, por exemplo New-*KbFront.ps1:
  • recebe NomeCurto, opcionalmente ExtraGuidCount, ReuseIfExists e AsJson
  • delega para scripts\New-GeneXusXpzFront.ps1 da base compartilhada
  • cria ou reutiliza a subpasta NomeCurto_GUID_YYYYMMDD em chamada atômica
  • devolve frontGuid, yyyymmdd, frontDir, createdAtUtc, GUIDs adicionais e motivo de bloqueio quando aplicavel
  • não decide sozinho se o trabalho e same front ou new front; essa decisão continua pertencendo ao fluxo da xpz-builder
  • este wrapper (ou o motor New-GeneXusXpzFront.ps1) é o passo que cria ou retoma a pasta da frente; popular (Copy-*KbAcervoToFront.ps1 / Copy-GeneXusAcervoToFront.ps1) e os gates que recebem -FrontFolder (9-FD Test-GeneXusFrontAcervoDrift.ps1 e os demais) operam sobre uma frente já existente e não criam a pasta — abrir a frente aqui, com -ReuseIfExists para retomar, antes de popular ou empacotar; criar a pasta manualmente é anti-padrão (o motor emite o erro FRENTE_NAO_ABERTA quando a frente não existe)
• Quando agentes atualizarem lastUpdate em XMLs locais com frequência, recomendar wrapper local fino para timestamp, por exemplo Get-*KbLastUpdate.ps1:
  • recebe opcionalmente Count, AsJson, baseline oficial e margem de frescor
  • delega para scripts\Get-GeneXusXpzLastUpdate.ps1 da base compartilhada
  • retorna timestamp UTC no formato yyyy-MM-ddTHH:mm:ss.0000000Z
  • quando receber baseline oficial, calcula max(UtcNow + margem, lastUpdate do baseline + margem), com margem padrão de 60 segundos
  • não substitui a classificação modified in this round vs reused unchanged for mandatory dependency closure; apenas fornece o instante canonico para objetos realmente alterados
• Quando o empacotamento local com import_file.xml for recorrente, recomendar wrapper local fino para criacao do pacote, por exemplo New-*KbImportPackage.ps1:
  • recebe FrontName, NN e opcionalmente TemplatePackagePath e AcervoPath (override do acervo; quando omitido, o motor resolve o acervo canonico <RepoRoot>/ObjetosDaKbEmXml da pasta paralela); a saida de maquina e JSON por padrão no stdout, sem -AsJson
  • delega para scripts\New-XpzImportPackage.ps1 da base compartilhada
  • o wrapper compartilhado chama o motor interno Python scripts\New-XpzImportPackage.py (chamada direta ao .py não é rota operacional equivalente), le kb-source-metadata.md, resolve as pastas padrão da pasta paralela, classifica raizes Object/Attribute, executa sempre o gate de drift frente-vs-acervo 9-FD (Test-GeneXusFrontAcervoDrift.ps1) em modo fail-closed antes do empacotamento, executa o gate de colisao e monta o pacote; no gate 9-FD, -AcervoPath e opcional e, quando omitido, o acervo canonico <RepoRoot>/ObjetosDaKbEmXml e resolvido automaticamente — sem acervo resolvivel o empacotamento e bloqueado, e o JSON reporta acervoResolvedBy (explicit ou convention); bloqueios esperados voltam como JSON estruturado com status, exitCode, stage e blockingReasons, nunca como stack/ANSI para consumo de maquina
  • quando TemplatePackagePath for informado, o motor aceita import_file.xml ou .xpz real comparavel, clona KMW, Source, Dependencies, ObjectsIdentityMapping e, quando não houver Attribute explicito na frente, preserva também Attributes de topo do template; para Panel, um par level id/layout id localizado nesse template comparavel pode ser registrado como confirmado; quando omitido, usa envelope mínimo derivado de kb-source-metadata.md e retorna warning para pacote misto/complexo, com ressalva específica de par não verificado para Panel
  • este wrapper reduz comando local e facilita allowlist, mas sua ausencia isolada não bloqueia wrappers_atualizados enquanto a KB puder chamar o motor compartilhado diretamente com -RepoRoot
• Quando agentes precisarem diagnosticar código C# gerado após import/build, recomendar wrapper local fino para resolver caminho de .cs, por exemplo Resolve-*KbGeneratedCsPath.ps1:
  • recebe KbPath, ObjectName, opcionalmente ObjectType, EnvironmentName e AsJson
  • delega para scripts\Resolve-GeneXusGeneratedCsPath.ps1 da base compartilhada
  • le kb-source-metadata.md e usa kb_environment_web_dirs para montar <webDir>\<objectName-lowercase>.cs sem varredura recursiva da KB nativa
  • se kb_environment_web_dirs estiver ausente ou sem o environment solicitado, retorna BLOCK e orienta executar xpz-kb-parallel-setup para reconciliar o metadata; não aceitar chute de diretório nem scan de C:\GxModels
  • exceção (guarda de família do Eixo B): KB com deployment_hosting_kind de família não-.NET (java-tomcat, Eixo B sourceSupportState=recognized-no-engine, Pós-v1 — o Eixo A roda o co-gate Java) retorna CS_PATH_SKIPPED_HOSTING_UNSUPPORTED (exit 0, sem csPath) antes do bloqueio de web_dirs — o skip não exige web_dirs (o artefato Java não é .cs)
  • e somente leitura: não grava, não abre a KB e não invoca MSBuild
• Quando o fluxo iterativo de import+build produzir o sub-estado importação real efetiva provada, geração de runtime pendente ou o usuário reportar que o comportamento ainda não mudou após import e build, a checagem de frescor de runtime pode ser executada diretamente pelo script da base compartilhada scripts\Test-GeneXusRuntimeFreshness.ps1 — não requer wrapper local:
  • -KbPath (obrigatório): caminho da KB GeneXus nativa (onde reside nav_objs.xml)
  • -ObjectName (obrigatório): nome do objeto GeneXus a verificar
  • -ImportedAt (obrigatório): timestamp do import como linha de corte (string ISO parseable)
  • -ObjectType (opcional): tipo GeneXus do objeto; reservado para uso futuro
  • -GeneratorOutputPath (opcional): pasta de output do gerador; antes de informar este parâmetro para diagnostico de .cs em KB multi-environment, resolver o caminho com scripts\Resolve-GeneXusGeneratedCsPath.ps1/Resolve-*KbGeneratedCsPath.ps1 a partir de kb_environment_web_dirs; se omitido, o script legado deriva <KbPath>\CSharpModel\web, o que e apenas complementar e não substitui metadata de output por environment
  • -DeploymentHostingKind (obrigatório em KB de família não-.NET quando conhecido, especialmente java-tomcat): passar java-tomcat para que o Eixo C pule com skipped-hosting-unsupported/exit 0 em vez de aplicar heurística .NET sobre nav_objs.xml e CSharpModel\web
  • -AsJson (opcional): emite saída JSON estruturada em vez de texto humano