xpz-builder

name	xpz-builder
description	Generates and clones GeneXus XPZ objects conservatively — validates structure, applies risk rules, serializes envelope

xpz-builder

Generates GeneXus XML objects for XPZ packaging using conservative cloning from empirical templates. Applies risk rules, validates structure, and serializes the correct XPZ envelope. Does not affirm import or build success — that requires external IDE validation.

---

GUIDELINE

Generate or clone GeneXus XPZ objects only from comparable structural templates. Abort when a suitable template does not exist. Never invent structure.

If the flow depends on a KB parallel folder structure and that structure is not yet mounted or validated, stop and use xpz-kb-parallel-setup first.

PATH RESOLUTION

• This SKILL.md lives inside a skill subfolder under the repository root.
• Resolve every ../arquivo.md reference relative to the directory of this SKILL.md, not relative to the current working directory.
• In practice, ../ points to the shared methodological base in the parent directory of this skill folder.

---

TRIGGERS

Use this skill for:

• User asks to generate an XPZ for a specific GeneXus object type
• User asks to clone, rename, or adapt an existing XML object
• User asks to package one or more objects into an XPZ envelope
• User asks to validate an XML object before packaging
• User asks which template or molde to use for a given object type
• User asks how to construct the <ExportFile> envelope

Do NOT use this skill for:

• Analyzing or classifying existing XML without modification intent (use xpz-reader)
• Questions about GeneXus runtime, build behavior, or IDE configuration
• Generating KnowledgeBase-level exports or full KB backups
• Affirming that generated XPZ will import or build without errors
• Locating or finding objects in the KB corpus by name, type, or function (use xpz-index-triage first when a KbIntelligence index is available)

If the main need is to prepare or validate the initial folder structure around the KB before any packaging flow, use xpz-kb-parallel-setup.

---

RESPONSIBILITIES

• Identify the target object type and locate the most comparable structural template
• Apply risk assessment from 03-risco-e-decisao-por-tipo before proceeding
• Abort if no comparable structural template exists and risk is high or very high
• For each GeneXus object type present in the batch, load the corresponding satellite under responsibilities-by-type/ end-to-end before generating, editing, or packaging the XML, in addition to this SKILL.md. Satellites consolidate type-specific RESPONSIBILITIES and QUALITY CHECKLIST entries. Available satellites: responsibilities-by-type/transaction.md (Transaction), responsibilities-by-type/webpanel.md (WebPanel), responsibilities-by-type/panel.md (Panel, especialmente Panel SD), responsibilities-by-type/dataprovider.md (DataProvider), responsibilities-by-type/api.md (API; carrega também responsibilities-by-type/api-gam-runtime.md, a pré-condição de segurança GAM em runtime que bloqueia declarar "seguro" sem o smoke 2 fases), responsibilities-by-type/procedure.md (Procedure, incluindo simple report Procedure), responsibilities-by-type/workwithforweb.md (WorkWithForWeb).
• Treat any extra block opened after the first one as an adjacent block and open it only when there is explicit functional dependency with the primary edit block
• Name every justified block transition in the review or packaging rationale, instead of silently widening the edit scope
• State the intended conclusion or effect scope at the smallest functional level supported by the delta, including execution context when that distinction matters
• Clone conservatively: preserve Object/@guid, parent*, moduleGuid, all recurring Part types
• Apply XPZ envelope rules from 02-regras-operacionais-e-runtime
• Choose package format for deltas of existing objects by validated local precedent first, distinguishing explicitly between embedded-object packages under <Objects> and packages that use <FilePath> to point to external XML
• Treat local precedent as strong only when the same KB trail shows compatible object type, compatible operation nature, and compatible batch materialization style
• Abort for confirmation instead of extrapolating from weak analogy when no strong enough local precedent justifies the package format
• Treat runtime, Import File Load, Import, and Specification as distinct validation layers; success in one does not authorize conclusions about the others
• Validate Source compatibility by methodology first: GeneXus semantic rules plus the XPZ trail and nexa; use KB corpus search only as fallback when the methodological base does not cover the case
• Separate explicitly well-formed XML from probably importable object before packaging; never treat XML parse success alone as enough when the object depends materially on Source
• When a local XML candidate already exists on disk and depends materially on Source, run ..\scripts\Test-GeneXusSourceSanity.ps1 -InputPath <arquivo> before packaging; treat sourceSanityStatus=fail as a hard stop and warn as consultative conservative review
• Classify each package candidate by content delta as requested change, necessary auxiliary change, or extra unrequested change before packaging
• Require explicit signaling before packaging when a candidate item remains as extra unrequested change, including metadata, reserialization, or known noise that is not strictly required
• Generate valid GeneXus lastUpdate timestamp by mechanical rule, not by literal guess: for a modified object use max(UtcNow + 60s, official-corpus lastUpdate + 60s) and then reread the saved XML to confirm the persisted value
• Preserve the official lastUpdate only for objects that are intentionally reenviados sem mudanca as dependency or package-composition closure
• Treat lastUpdate equal to or older than the official corpus as a blocking defect when the object was modified in the round
• Treat manually rounded timestamps, copied timestamps from another file, copied baseline lastUpdate on a modified object, or arbitrary future values as invalid lastUpdate generation
• Treat ObjetosDaKbEmXml as official snapshot and read-only for agents
• Treat any detected or intended edit in ObjetosDaKbEmXml for a delta that has not yet returned by official KB re-export as an explicit process error, not as a mere operational detail
• Editing ObjetosDaKbEmXml does not affect the packaging output — the packaging motor reads from the front folder (ObjetosGeradosParaImportacaoNaKbNoGenexus/<Frente>/), never from the corpus; if the agent edits the corpus expecting the package to pick up that version, the package will use the stale version from the front; this is an anti-pattern that the 9-FD gate detects (see 02-regras-operacionais-e-runtime.md, anti-padrão "editar acervo esperando que o pacote pegue")
• If the object has not yet returned from the KB by official export, perform the work only in ObjetosGeradosParaImportacaoNaKbNoGenexus
• When creating an altered copy of GeneXus XML in ObjetosGeradosParaImportacaoNaKbNoGenexus, preserve the source XML outside the approved functional delta; the default operation is surgical editing, not broad reconstruction or full-file reserialization
• Outside the approved delta, preserve comments, CDATA, indentation, blank lines, node order, line endings, and inherited whitespace; do not introduce trailing spaces or tabs on new or modified lines
• Before packaging, compare the altered copy against the source XML and confirm that the diff contains only the intended delta; whitespace-only changes, indentation churn, line-ending churn, removed comments, or serialization churn outside the delta are process noise and must be corrected or explicitly approved before delivery
• git diff --check is not authorization to clean the whole XML file. Mechanical protection is partial in this version: the 9-FD gate used by New-XpzImportPackage.ps1 detects strong removal of inherited trailing whitespace against a unique-GUID baseline; it does not detect newly introduced trailing whitespace and is not a complete whitespace, reindentation, or EOL detector. front-textual-fidelity-info is informational only when there was a unique-GUID baseline but comparable UTF-8 text reading/decoding failed. On textual blocking, rebuild via Copy-GeneXusAcervoToFront.ps1 with an explicit target (-ObjectList, -ObjectNames, or -ObjectGuids) and reapply only the functional delta; explicit targets may overwrite an already edited/newer front copy.

Edição cirúrgica de XML e limitações da ferramenta Edit do harness

• Fluxo obrigatório: copiar o XML oficial de ObjetosDaKbEmXml para a frente em ObjetosGeradosParaImportacaoNaKbNoGenexus e editar somente o delta funcional aprovado na cópia de trabalho; nunca editar ObjetosDaKbEmXml diretamente.
• A edição cirúrgica padrão não é a ferramenta Edit do harness (substituição por trecho em chat) em XML GeneXus com Source, Rules ou CDATA longos. Essa ferramenta pode: (1) normalizar linhas em branco indentadas (tabs/espaços herdados) para quebra de linha pura; (2) tratar \n\t\t\t\t\n e \n\n como equivalentes na comparação, impedindo correção por novo Edit; (3) introduzir espaços ou tabs no fim de linha ou ampliar o diff para longe do trecho pretendido.
• Preferido para alterar XML de objeto: scripts/Edit-GeneXusXmlSurgical.ps1 (modos Replace e InsertAfter, validação de âncora, bump automático de lastUpdate com escape -PreserveLastUpdate para dependência reenviada sem mudança, -DryRun e -AsJson). Quando o baseline oficial estiver disponível, passar -LastUpdateBaselinePath apontando para o XML em ObjetosDaKbEmXml. Exemplo copiável: examples/Edit-GeneXusXmlSurgical.example.ps1. Evitar script ad-hoc por frente ou a ferramenta Edit do harness como caminho principal.
• Regravar o arquivo inteiro com Write só para XML pequeno e montado programaticamente a partir da leitura raw da origem; para Procedure/WebPanel/Transaction com Source longo, tratar Write do arquivo completo como alto risco de churn e evitar como caminho padrão.
• Não confiar em nova tentativa da mesma ferramenta Edit só para “recolocar” tabs em linhas em branco ou remover trailing spaces.
• Antes de empacotar: comparar a cópia alterada com o XML de origem da mesma frente. Se o diff trouxer mudanças fora do bloco primário declarado, whitespace-only fora do delta, linhas em branco com indentação herdada alteradas, trailing spaces novos em linhas não tocadas funcionalmente, ou centenas de linhas alteradas longe do delta → ABORT, refazer por script/raw e registrar o ruído como erro de processo.
• Quando a edição tiver usado Edit do harness ou o diff suspeitar de whitespace: inspecionar com scripts/Show-FileWhitespace.ps1 (modos whitespace ou mixed; -AsJson para agentes) conforme AGENTS.md na raiz do repositório ativo — no arquivo inteiro ou no intervalo de linhas do delta.

Edição combinada de Source + Variables em objeto existente

• Quando o delta inserir código em Source/CDATA e também criar ou alterar variáveis, declarar explicitamente a transição de bloco Source -> Variables (ou events -> variables, conforme o tipo) como bloco adjacente justificado; não tratar a seção Variables como detalhe implícito do patch de código.

• Antes de montar o patch, medir a política textual do XML-alvo: EOL real do arquivo, regra aplicável em .gitattributes do repositório da KB, presença de BOM e estilo dominante de indentação no trecho. Em KB real analisada, Source usava tabs e Variables usava espaços, mas isso é evidência de corpus, não licença para sobrescrever o estilo do arquivo-alvo.

• Para inserir em Source, preferir scripts/Edit-GeneXusXmlSurgical.ps1 com âncora literal e -DryRun; o Replacement deve ser construído já com a quebra de linha e a indentação observadas no arquivo-alvo. O helper preserva o texto fora do delta e faz bump de lastUpdate, mas não inventa a indentação correta para o chamador.

• Para apenas re-carimbar o lastUpdate de um XML da frente já editado (rodada 2+), sem copiar do acervo nem aplicar delta, usar scripts/Set-GeneXusXmlLastUpdate.ps1 (-InputPath, -BaselineXmlPath opcional, -DryRun, -AsJson): recalcula max(UtcNow + margem, baseline + margem) e grava in-place com backup e validação, em vez de busca-e-troca manual do atributo. Sem -BaselineXmlPath, o baseline é o próprio arquivo — suficiente para ficar acima do objeto vivo na KB, que preserva o lastUpdate importado como Modified Date; para garantir acima do acervo, apontar -BaselineXmlPath para o XML oficial em ObjetosDaKbEmXml.

• Para criar variável, não montar um bloco rígido universal. Clonar primeiro uma variável comparável do próprio objeto; se não existir, procurar uma variável comparável em objeto do mesmo tipo e da mesma KB; só então recorrer a molde sanitizado. Preservar a indentação estrutural da seção Variables.

• O corpus real mostra famílias de tipagem por idBasedOn=Domain:*, idBasedOn=Attribute:*, ATTCUSTOMTYPE=bas:*, sdt:*, exo:*, bc:*, ext:* e formas legadas sem idBasedOn/ATTCUSTOMTYPE. Portanto, validações amplas sobre todo o legado devem ser consultivas; checks bloqueantes devem focar as variáveis novas ou declaradas como tocadas no delta.

• Depois de inserir ou alterar variáveis, executar scripts/Test-GeneXusObjectVariableDelta.ps1 -InputPath <xml> -VariableName <nomes> -AsJson para as variáveis novas/tocadas. Tratar status=fail como bloqueio antes do pacote; tratar status=warn como revisão conservadora explícita. Sem -VariableName, o script é varredura consultiva do objeto inteiro, não reprovação automática do legado.

• Não validar ingenuamente todas as ocorrências de &X no Source contra <Variables>: o corpus contém entidades XML, variáveis especiais e formas geradas que produzem falsos positivos. Para pacote, validar as variáveis do delta e o trecho funcional tocado.

• Alterar Source ou Variables no XML não altera lastUpdate por si só. O arquivo final modificado deve sair com lastUpdate calculado pelo helper ou por regra equivalente antes de empacotar; checksum defasado pode ser observado como ressalva, mas não substitui o gate de lastUpdate.

• The set of standard KB parallel-folder subfolders (ObjetosDaKbEmXml, XpzExportadosPelaIDE, scripts, Temp, KbIntelligence, ObjetosGeradosParaImportacaoNaKbNoGenexus, PacotesGeradosParaImportacaoNaKbNoGenexus) and their recommended creation order are normative in the xpz-kb-parallel-setup skill — see xpz-kb-parallel-setup/SKILL.md. This builder assumes those names by default and falls back to xpz-kb-parallel-setup when alternative naming, structural ambiguity, or missing setup is detected.

• If XpzExportadosPelaIDE does not exist yet, ask where the user wants to store exported .xpz files

• If ObjetosDaKbEmXml does not exist yet, stop and treat the KB as not yet materialized

• Use ObjetosGeradosParaImportacaoNaKbNoGenexus as the working area for locally generated or preserved XML

• For each active front, create or reuse a dedicated subfolder under ObjetosGeradosParaImportacaoNaKbNoGenexus in the format NomeCurto_GUID_YYYYMMDD

• Treat YYYYMMDD in that identifier as the creation date of the front, defined at the same moment the GUID is created; it is not the package date

• Distinguish explicitly between same object and same front

• Do NOT reuse front identity, short-name prefix, front GUID, front creation date, or package counter only because the target object is the same

• Reuse the existing front subfolder only when the work is explicitly confirmed or directly evidenced as a continuation of that same front; do NOT create a second front folder for the same active front without explicit reason

• Use PacotesGeradosParaImportacaoNaKbNoGenexus as the destination area for locally generated packages

• Detect workspace contamination before packaging and abort when more than one plausible batch is active

• Treat the workspace as contaminated when the active root of ObjetosGeradosParaImportacaoNaKbNoGenexus contains XMLs from different fronts, different target objects, superseded deltas, or unrelated older files that could be mistaken for the current batch

• Build or validate a manifest for the candidate batch before packaging, treating the manifest first as structured output in the conversation

• When an earlier round of the same front has already been validated, the next round should prefer a delta package with the new increment, not an unnecessarily large accumulated package

• Reusing the same front does not authorize automatically re-packaging the whole active history of that front; the candidate batch for the current round must be reduced to the delta that is still needed

• A phased front is a legitimate pattern when a GeneXus operational limitation makes a safe monolithic package impractical; in that case, splitting the delivery into sequential rounds is part of the methodology, not an ad hoc workaround

• Classify the package intent explicitly before packaging as exactly one of:

  • pacote funcional = objetivo principal e alterar comportamento funcional esperado
  • pacote experimental = objetivo principal e testar serialização, roundtrip IDE/XPZ, preservação textual, envelope ou comportamento metodológico do fluxo
  • pacote arquitetural = objetivo principal e reorganizar estrutura, dependências ou forma de implementação sem provar sozinho mudança funcional
  • pacote cirurgico = objetivo principal e corrigir falha localizada ou objeto pontual com delta mínimo

• Treat that package-intent classification as mandatory narrative context, not as optional labeling

• Require a single primary intent per package; if the candidate batch mixes functional change, textual experiment, and architectural adjustment without clear separability, ABORT for confirmation or split the package plan before writing

• For pacote experimental, describe the expected proof narrowly and do not imply functional validation unless an external IDE/import/specification step actually covered it

• When the user already signals manual IDE import/testing, treat import_file.xml as the primary deliverable and generate it promptly instead of postponing packaging

• Prefer import_file.xml as the operational package artifact for manual IDE import unless .xpz is explicitly required by the user or by a documented local flow

• Do NOT generate .xpz as an extra artifact by default when import_file.xml already satisfies the intended manual IDE import flow

• Name locally generated packages for IDE import using the preferred pattern NomeCurto_GUID_YYYYMMDD_nn.import_file.xml

• In that package name, the front is identified only by the prefix NomeCurto_GUID_YYYYMMDD; nn is only the short package round for that front

• For successive micro-adjustments in the same active front, keep the same front subfolder and the same package prefix NomeCurto_GUID_YYYYMMDD; advance only nn

• Before writing NomeCurto_GUID_YYYYMMDD_nn.import_file.xml, run a deterministic collision gate in .ps1; do NOT leave this decision to ad hoc reasoning

• Shared packaging helpers emit machine JSON on stdout by default and do not use -AsJson; update old local wrappers through xpz-kb-parallel-setup

• When the recommended helper Build-GeneXusImportFileEnvelope.ps1 is used, the collision gate is embedded and runs before any byte is written; the file is materialized only when the gate returns JSON with status=ok

• When the recommended helper Build-GeneXusImportFileEnvelope.ps1 is used, pass -AcervoPath <ObjetosDaKbEmXml>; before serializing the package, the helper always checks front-vs-acervo coherence: the lastUpdate gate and Object/@type drift by same guid. Declaring modified objects with -ModifiedObjectNames or -ModifiedObjectGuids lets it block lastUpdate older than the acervo, lastUpdate equal to the acervo for declared modified objects, and unjustified future timestamps. It still covers documentary coherence of lastUpdate and Object/@type under its current contract, but it does not cover strong global trim in this version.

• When the target flow is headless MSBuild import (xpz-msbuild-import-export) and the object XML already exists in the parallel KB tree (ObjetosDaKbEmXml as read-only reference or ObjetosGeradosParaImportacaoNaKbNoGenexus as working copy), prefer assembling import_file.xml with a shared structured engine: Build-GeneXusImportFileEnvelope.ps1 for direct template-based assembly, or the safe wrapper New-XpzImportPackage.ps1 for front-based assembly from the parallel KB folder. Use a validated template (KMW, Source, ObjectsIdentityMapping from local precedent, or metadata such as kb-source-metadata.md per xpz-kb-parallel-setup for simple/minimal envelopes), then import that package — do not run a KB export only to obtain a .xpz "shell" to patch in parallel XML unless the user explicitly requests that path or confirms that envelope metadata cannot be obtained otherwise (if an exported .xpz is used anyway, xpz-msbuild-import-export requires a full pre-import object inventory)

• For compact inspection of XML/XPZ without dumping large CDATA, use scripts\Extract-XpzObject.ps1, scripts\Get-GeneXusObjectSummary.ps1, and, for Panel shape checks, scripts\Compare-GeneXusPanelShape.ps1 before resorting to raw Select-String or broad rg output; when comparing Panel SD, observe at least actionEventCoverage, namedEventNames, standardEventNames, variableEventNames, and tapEventNames. For WebPanel, the same script exposes a webpanel block (tables with tableType, controls, buttons in both forms, events, and a coverage block); load responsibilities-by-type/webpanel.md before editing WebPanel layout or events. To add a button to a WebPanel, prefer scripts\Add-GeneXusButton.ps1 (inserts before or after a named leaf control in a Flex table via -BeforeControlName/-AfterControlName; fail-closed on populated Responsive) instead of hand-editing the CDATA.

• If a textual search in the corpus returns multiple XML paths, list every match, state a recommended path with reason from user context, and confirm before opening one file; never default to the first tool result.

• In the manual fallback path (textual envelope assembly without the helper), prefer a local wrapper such as Test-*KbPackageCollision.ps1, delegating to the shared engine scripts\Test-XpzPackageCollision.ps1

• If the collision gate returns JSON with status=bloqueado or non-zero exit code, abort the write; do NOT silently overwrite that round

• When there is an nn collision, the suggested next free nn must come from the collision gate output itself; do NOT auto-increment or write automatically with the suggested value

• Keep PacotesGeradosParaImportacaoNaKbNoGenexus flat, without subfolders by front

• Classify each active XML root as Object, Attribute, or unsupported before serializing the package

• Validate UTF-8 without BOM hygiene on active XMLs before packaging

• Validate textual delta fidelity on active XMLs before packaging: only the approved functional delta should appear in comparison against the source XML

• Reread and apply local repository documentation (AGENTS.md, README.md, and equivalent project docs) before packaging whenever the target KB/repository defines specific functional review rules, contracts, or operational flow

• Use local repository documentation as the mandatory specialization layer for KB-specific contracts and review chains, without promoting those local rules to the shared XPZ methodology

• Keep general XPZ methodology separate from KB-specific architecture; flows such as WorkWithWeb -> action -> parm(...) -> For each may be mandatory in a given repository but are not universal GeneXus or XPZ rules

• Ensure all GUIDs are syntactically valid (no text placeholders like "YOUR-GUID-HERE")

• Validate XML structure before delivery

• Declare confidence level and limitations explicitly at the end of every output

• When generating an object for a small or new KB that has no comparable local XML: follow the resource ladder from 08-guia-para-agente-gpt.md; if reaching level 2 (best-effort attempt without commitment), declare explicitly which source sustains the generation (molde sanitizado, XML real da KB atual, XML real de KB externa inspecionada, or hipótese), signal the confidence level, and require validation before import; if the probability of success is assessed as low, present the options to the user and wait for a decision before generating

• Keep WorkWithWeb noise that is already proven in this trail as non-functional in the manifest, especially Load Code in Selection and the affected View tabs; do not generalize this to unrelated WorkWithWeb cases

• When declaring a variable as an SDT collection in any object type (API, WebPanel, Procedure, DataProvider): use AttCollection=True; NEVER use Collection=True or IsCollection=True — both are invalid and will be rejected; this applies to the variable's <Properties> block in the XML

  • for collection reinitialization introduced by the current Source delta and already covered by the methodological base, prefer = new(); do NOT accept unsupported cleanup forms such as SetEmpty() only by plausibility or analogy
  • if a period filter is introduced over a DateTime field, prefer direct comparison on the DateTime column: >= start and < next day after end
  • treat function on the database column, especially ToDate() over the column, as explicit navigation/performance risk
  • if a function on the column is kept, justify it explicitly
  • when the user asks for an initial-date/final-date pair, prefer two independent where clauses instead of branching into unnecessary scenarios
  • when the object already has a clear local form in Source, prefer following that form as a weak readability heuristic, not as a hard methodological rule

• When the candidate batch contains 2 or more distinct objects, run the Import Dependency Ordering gate (9-IDO) after all other object-level gates: detect structural dependencies between batch objects, assign each object to a topological layer, alert when ordering risk exists across 2 or more layers, and ABORT when circular dependencies are found

---

COMMUNICATION

• Respond in the same language the user writes in
• Lead with the decision (proceed / abort) and the reason
• State which template was used and why it was selected
• State the package intent explicitly as pacote funcional, pacote experimental, pacote arquitetural, or pacote cirurgico
• When the case is experimental or methodological, say that clearly in the narrative and separate it from any claim about functional behavior
• Always end output with a limitations block: what was followed, what requires external validation
• In the closing, declare explicitly whether the front identity was confirmed, directly evidenced, or assumed under local rule
• In the closing, declare explicitly whether the package reused an existing front or opened a new front
• In the closing, declare explicitly why the final package name was chosen
• In the closing, explicitly state that the saved XML was reread, the persisted lastUpdate was confirmed, and the applicable local repository rules were reread and satisfied before packaging
• Use NEVER and ABORT as hard stops, not suggestions
• NEVER use speculative or reassuring language about import/build success

---

STRUCTURE

Reference files and when to load them:

Reference	Load when
00-indice-da-base-genexus-xpz-xml.md	Always — absolute rules and envelope structure
02-regras-operacionais-e-runtime.md	Always — envelope serialization, timestamp, GUID, ObjectsIdentityMapping rules
03-risco-e-decisao-por-tipo.md	Always — risk level and abort conditions
04-webpanel-familias-e-templates.md	Target is a WebPanel object
05-transaction-familias-e-templates.md	Target is a Transaction object
05b-procedure-relatorio-familias-e-templates.md	Target is a simple report Procedure, especially F2/F3 covered by molde pronto
07-open-points-e-checklist.md	Edge cases, provisional decisions, or checklist for new templates
08-guia-para-agente-gpt.md	Decision formula, precedence rules, materialization rules, refuse conditions
01j-workwithweb-cdata-padroes.md	When editing CDATA of a WorkWithForWeb object — CDATA hierarchy, anchor rules, sanitized examples
04b-ucw-gxcontroltype-reference.md	When the target is a WebPanel with UCW (<ucw gxControlType="...">) — gxControlType catalog, upload context table, event rules, SDT FileUploadData, AttCollection rule
xpz-index-triage skill	When a KbIntelligence index is available and locating comparable corpus XMLs or confirming object existence is needed before opening XML files

---

WORKFLOW

1. Identify the target object type and the user's intent (create new / clone existing / rename)
2. If the KB parallel folder structure is not yet mounted, not yet validated, or still ambiguous for this repository → ABORT and use xpz-kb-parallel-setup first
3. Reread local repository documentation and resolve the operational topology for this KB/repository:
   • ObjetosDaKbEmXml = official snapshot, read-only for agents
   • XpzExportadosPelaIDE = input area where the user stores .xpz exported by the IDE
   • ObjetosGeradosParaImportacaoNaKbNoGenexus = working area for local XMLs to import manually, organized by front subfolder NomeCurto_GUID_YYYYMMDD
   • each front subfolder is the active unit of that work front
   • PacotesGeradosParaImportacaoNaKbNoGenexus = output area for locally generated packages, kept flat without subfolders by front
   • if the object has not yet returned from the KB by official export, the work must stay in ObjetosGeradosParaImportacaoNaKbNoGenexus 3b. When the user goal is headless import via MSBuild and the delta XML already lives in the parallel folder, plan delivery as import_file.xml through Build-GeneXusImportFileEnvelope.ps1 (mandatory -AcervoPath <ObjetosDaKbEmXml>; front-vs-acervo coherence by lastUpdate and Object/@type; declare objects actually modified in the round via -ModifiedObjectNames or -ModifiedObjectGuids) or the front-based safe wrapper New-XpzImportPackage.ps1 flow (which also runs 9-FD textual fidelity, blocks strong removal of inherited trailing whitespace by unique-GUID baseline, and may emit informational front-textual-fidelity-info when there is a unique-GUID baseline but comparable UTF-8 text reading/decoding failed; partial protection, not a complete whitespace/reindentation/EOL detector) plus skill xpz-msbuild-import-export for execution + package inventory; do not default to KB export to manufacture a .xpz shell unless the user explicitly chooses that path or confirms envelope assembly is blocked 3c. For Panel, especially Panel SD, treat level id and layout id as an internally coherent pair. NEVER generate them as independent random GUIDs. Clone or preserve the pair from a comparable real template exported by the IDE from the same KB whenever possible; if the exact derivation rule is unknown, declare the risk and use a coherent template pair instead of isolated GUID substitution. 3d. When packaging a Panel, prefer a full comparable IDE-exported envelope through -TemplatePackagePath (accepted as .import_file.xml/XML or .xpz) so KMW, Source, Dependencies, Attributes when present, and ObjectsIdentityMapping come from a real package. If the package is generated from the minimal kb-source-metadata.md envelope, report that as a warning for Panel SD instead of implying equivalence with a full IDE envelope. 3e. For Panel SD with <action onClickEvent=...>, read the serialized behavior in detail/@events. Do not synthesize Event Controle.Tap without equivalent evidence in a comparable real Panel from the target KB; prefer a named Event 'Nome' whose quoted name matches the action onClickEvent.
4. Before generating or packaging a front, resolve the front identifier explicitly:
   • determine whether the case is same front or new front
   • do NOT infer same front only because the object is the same
   • if continuity was not explicitly stated and no direct repository evidence closes that ambiguity, block automatic inheritance of the previous front identity and follow the applicable local rule
   • When the repository publishes a local front-opening wrapper (for example New-*KbFront.ps1) or the shared engine scripts\New-GeneXusXpzFront.ps1 is directly approved, prefer that atomic wrapper/engine to create or reuse the front folder, generate the front GUID, calculate YYYYMMDD, and return any extra GUIDs needed by the batch
   • Treat front-opening wrappers as convenience and permission-hygiene helpers, not as proof that the front is semantically correct; the same front vs new front decision above remains mandatory
   • only after that, define:
     • NomeCurto
     • GUID generated when the front is opened
     • YYYYMMDD = creation date of the front, defined together with the GUID; it is not the package date
     • front folder = ObjetosGeradosParaImportacaoNaKbNoGenexus\NomeCurto_GUID_YYYYMMDD\
     • if that front folder already exists for the current front, reuse it
     • that front folder is the active unit of the work front 4b. Before listing the workspace, declare the round spec for this packaging round:
   • State explicitly which objects (name + type) are expected in the candidate batch for this round
   • This declaration must come from the user's intent or the front's declared scope — not from reading the workspace first
   • If the expected object list is unclear or has not been declared in this conversation → ask the user before proceeding to step 5
   • Record the declared list as the round spec for this round; it is the committed delivery target before the workspace is inspected
   • The declared round spec is also the authoritative source of objetos-foco for any xpz-sync invoked in the same session for this front
5. When the task is packaging, list active XMLs only inside the current front folder and treat them as the candidate batch
   • After listing, verify that the workspace matches the round spec declared in step 4b:
     • Object in round spec but absent from workspace → report the gap explicitly; do NOT silently proceed as if the object were already present
     • Object in workspace but absent from round spec → classify as potential contaminant; do NOT silently absorb into the batch
   • If workspace and round spec diverge, require explicit reconciliation before continuing to step 6
6. Before any package write, execute the deterministic collision gate for the intended FrontPrefix + nn in PacotesGeradosParaImportacaoNaKbNoGenexus:
   • When the package is assembled via Build-GeneXusImportFileEnvelope.ps1 (recommended path), pass mandatory -AcervoPath <ObjetosDaKbEmXml> and declare modified objects with -ModifiedObjectNames or -ModifiedObjectGuids; the collision gate is embedded: the helper runs Test-XpzPackageCollision.ps1 as its first action and aborts with zero bytes materialized when _nn is taken; the helper also blocks before writing when front-vs-acervo coherence fails by lastUpdate or by same guid with divergent Object/@type; this direct helper does not cover strong global trim in this version. For front-based assembly, use New-XpzImportPackage.ps1, whose 9-FD gate also blocks strong removal of inherited trailing whitespace by unique-GUID baseline and may emit informational front-textual-fidelity-info only when comparable UTF-8 text reading/decoding fails after such a baseline is found; in the direct-helper flow, no explicit pre-call to the wrapper is required
   • When the package is assembled via the manual fallback (textual envelope assembly without the helper), the collision gate must be executed explicitly before any Set-Content, rename, move, or overwrite of the package artifact
   • Prefer the local wrapper Test-*KbPackageCollision.ps1 when the KB/repository publishes it
   • The wrapper should delegate to the shared engine scripts\Test-XpzPackageCollision.ps1
   • Expected outputs (JSON on stdout by default, no -AsJson):
     • free round: status=ok, reason=COLLISION_OK, exit 0
     • collision: status=bloqueado, reason=PACKAGE_ROUND_COLLISION, blockingReasons, nextFreeNN/nextFreeRound, exit 20
   • If the gate blocks (status=bloqueado or non-zero exit code), ABORT packaging before any Set-Content, rename, move, or overwrite of the package artifact
7. Classify the package intent before packaging and record it in the conversation/manifests:
   • pacote funcional
   • pacote experimental
   • pacote arquitetural
   • pacote cirurgico
   • if the candidate batch does not have one dominant primary intent, ABORT and require split or explicit confirmation before packaging
   • if the case is pacote experimental, state the bounded proof target explicitly, such as serialização, roundtrip IDE/XPZ, preservação textual, or envelope/importação
   • if the case is pacote experimental, do NOT narrate the package as if it already proved business behavior
8. Evaluate batch isolation before packaging:
   • If more than one plausible batch is present inside the current front folder → ABORT
   • Do NOT infer the correct batch only from recency when there is contamination risk
   • If the current front needs a new isolated single-object delta and the current front folder contains remnant XMLs that do not belong to the current front decision, treat that front folder as contaminated and ABORT until the unitary batch is isolated explicitly
   • Treat a front-folder XML as a remnant contaminant when it is not part of the current front decision, is not part of the package being assembled now, was superseded by change of direction, or remains inside the active front folder without operational justification for the current batch
   • Preferred operational resolution for a new unitary delta: keep only the current object XML inside the current front folder as the active batch
   • Before generating new files, offer to move remnant contaminant XMLs from the current front folder to ArquivoMorto; do so only after explicit user approval
   • Do NOT silently reuse a contaminated front folder batch when the current front is unitary
   • Distinguish explicitly between artifact of the current front and pre-existing parallel change:
     • current-front artifact = XML intentionally produced, adjusted, or preserved for the current package decision
     • pre-existing parallel change = unrelated XML/package/workspace modification that already existed and is not part of the current batch decision
   • Do NOT absorb pre-existing parallel changes into the package of the current front only because they are present in the workspace
   • Classify current-batch content as requested change, necessary auxiliary change, or extra unrequested change
   • Signal any extra unrequested change explicitly before packaging; do NOT silently absorb it into the package
   • When the agent received a package from MSBuild export or another source with more objects than the declared delta, treat surplus items as extra unrequested change until the user explicitly accepts them; ABORT packaging rather than merging surplus into the surgical import package
   • If an older package lost validity after a change of direction, either rename it with prefix OBSOLETO_ or present a structured manifest in the conversation stating that package X was replaced by package Y; save that manifest as a local file only when local traceability is concretely needed 9-BC. BC dependency preflight gate — run before any packaging when the batch contains a Procedure:
   • Run & ..\scripts\Test-GeneXusBCDependency.ps1 -FrontFolder <pasta-da-frente> -CorpusFolder <ObjetosDaKbEmXml> -AsJson
   • not-applicable (no Procedure in the batch) → proceed normally
   • pass (all BC dependencies resolved as info; Transactions exist as BC in the corpus) → proceed normally
   • alert (one or more warn findings) → present each warn finding to the user; require explicit confirmation to package the Procedure(s) and Transaction(s) together, or stage into two packages — package 1 with the Transaction(s), package 2 with the dependent Procedure(s)
   • fail (any fail finding) → ABORT packaging; report each finding (procedureName, transactionName, code, location) and the corrective action implied by the code:
     • bc-isbc-false-batch / bc-isbc-property-absent-batch: correct the Transaction XML in the batch to set idISBUSINESSCOMPONENT=True before packaging
     • bc-isbc-false-corpus / bc-isbc-property-absent-corpus: the Transaction exists in the official corpus but is not a Business Component; the bc: dependency cannot be satisfied without correcting and reimporting the Transaction first
     • bc-missing-everywhere: the Transaction is absent from both the batch and the official corpus; add it to the batch or confirm its existence in the target KB before packaging
     • bc-sublevel-not-found-batch / bc-sublevel-not-found-corpus: the Transaction exists as BC, but the sublevel referenced by bc:<Transaction>.<Sublevel> is not present in its Levels; correct the BC reference or the Transaction structure before packaging
   • Do not package while any fail finding remains unresolved 9-WW. WorkWithWeb Apply-mark preflight gate — run before any packaging when the batch contains a WorkWithForWeb object:
   • Run & ..\scripts\Test-GeneXusWorkWithWebApply.ps1 -FrontFolder <pasta-da-frente> -CorpusFolder <ObjetosDaKbEmXml> -AsJson
   • The script detects each WorkWithForWeb's structural form (Form A = Part babfa2b2-... with explicit Apply property; Form B = Part a51ced48-... with <Data Pattern="..."> and linked Transaction in CDATA; Form B implicitly treats Apply as True), resolves the linked Transaction name (Property in Form A, <transaction transaction="<guid>-<name>" /> element in Form B), and verifies Apply:78cecefe-be7d-4980-86ce-8d6e91fba04b = True on that Transaction in the batch or in the corpus.
   • not-applicable (no WorkWithForWeb in the batch) → proceed normally
   • pass (only info findings: Apply:GUID=True confirmed in batch or corpus) → proceed normally
   • alert (one or more warn findings) → review each finding; for ww-form-a-apply-false confirm whether pattern disablement is intentional; for ww-applyguid-absent-corpus verify KB state preserves the pattern; for ww-applyguid-tx-missing document the gap before packaging
   • fail (any fail finding) → ABORT packaging; the script reports each finding with code and the corrective action implied:
     • ww-no-form-detected: the XML is unrecognizable as a WorkWithForWeb in either expected form — structural error
     • ww-form-a-apply-property-absent: add <Name>Apply</Name><Value>True</Value> to the Part babfa2b2-... before packaging
     • ww-linked-transaction-missing: the WorkWithForWeb does not expose the linked Transaction name in an extractable way — fix the source XML
     • ww-applyguid-false-batch: the linked Transaction is in the batch but lacks Apply:78cecefe-...=True — add the property before packaging
   • The script also emits info findings for diagnostic context (ww-both-forms-detected for the rare case of coexistence, ww-applyguid-true-batch/ww-applyguid-true-corpus for confirmed cases). These do not require action. 9-TWS. Transaction Coherence preflight gate — run before any packaging when the batch contains a Transaction:
   • Run & ..\scripts\Test-GeneXusTransactionCoherence.ps1 -InputPath <arquivo> -AsJson for each Transaction XML in the batch
   • not-applicable (object is not a Transaction or no Transaction found) → proceed normally
   • fail → ABORT: correct the structural issue (missing key in Level, DescriptionAttribute not found in Level, or WorkWithPlus DVelop screen code — Call("LoadWWPContext")/Call("<Trn>WW") — carried by a GenerateObject=False Transaction, finding wwp-screen-code-on-non-generated-transaction; see responsibilities-by-type/transaction.md) before packaging
   • warn → keep packaging blocked; each flagged finding must be reviewed and either corrected or explicitly justified before proceeding; accepted justifications must be recorded in the closing declaration
   • pass → proceed to next gate 9-TXW. Transaction Writability gate — run before any packaging when the batch contains a Transaction whose delta involves Rules or Events with attribute assignments:
   • When the parallel KB has a fresh KbIntelligence index (schema_version>=2), you may use transaction-writable-attributes for triage before opening XMLs; packaging still requires Test-GeneXusTransactionWritability.ps1 unless Test-GeneXusKbIntelligenceWritabilityParity.ps1 has passed on that parallel KB folder
   • Run & ..\scripts\Test-GeneXusTransactionWritability.ps1 -TransactionPath <transaction.xml> -CorpusFolder <ObjetosDaKbEmXml> -AsJson for each Transaction XML whose delta assigns attributes (PowerShell facade over GeneXusTransactionWritabilityCore.py)
   • The script is descriptive: it returns pass after classifying every (level, attribute) pair into levelAttributes with writable=true|false|null and a classification (key-attribute, extended-parent-fk, formula, extended-subtype-key, extended-subtype-descriptive, extended-fk-key, extended-fk-descriptive, own-physical, unclassified-attribute-not-found, unclassified-table-not-found)
   • Any attribute with writable=false must be excluded from assignments in the delta; assigning to a non-writable attribute requires an explicit ABORT of the assignment before packaging
   • writable=null (any unclassified-* classification) means the corpus lookup did not resolve and the writability cannot be decided; resolve the corpus gap or document the limitation before assigning that attribute
   • This gate never returns fail by itself — the ABORT comes from the assignment policy above 9-PNW. Procedure New Writability gate — run before any packaging when the batch contains a Procedure whose Source contains New:
   • Run & ..\scripts\Test-GeneXusNewWritableTargets.ps1 -FrontFolder <pasta-da-frente> -CorpusFolder <ObjetosDaKbEmXml> -AsJson (PowerShell facade; writability classification via GeneXusTransactionWritabilityCore.py batch)
   • The script extracts direct left-side assignments inside each New/EndNew block, infers candidate Transaction targets from the assigned attribute set, and applies the same writability classifications used by 9-TXW.
   • pass (only info findings) → proceed normally
   • alert (ambiguous target with all assigned attributes writable in more than one candidate) → confirm and record the intended base table before packaging
   • fail (new-assignment-non-writable, new-assignment-unclassified, or new-target-unresolved) → ABORT packaging; remove the invalid assignment or prove the intended base table with a stronger local reference before re-running
   • Never treat an attribute as writable in New only because it is visible, inferable, descriptive, formula-derived, or reachable through an extended table; the target must be physically assignable in the base table inferred for that New 9-PSM. Procedure Sub-pattern Mirroring gate (advisory) — run before any packaging when the batch contains a Procedure:
   • Run & ..\scripts\Test-GeneXusProcedureSubPattern.ps1 -FrontFolder <pasta-da-frente> -CorpusFolder <ObjetosDaKbEmXml> -AsJson
   • not-applicable (no Procedure in the batch) → proceed normally
   • pass (only info findings: no pattern to mirror, Procedure new, or new Sub coherent with dominant pattern) → proceed normally
   • alert (one or more warn findings with code psm-new-sub-mixed-diverges) → present each alert to the user using the message from the script; the dominant pattern (iterationSub → unitSub) is in the finding's dominantPattern field; require the user to either confirm the divergence is intentional (justification recorded in the closing declaration) or restructure the new Sub to mirror the pattern before packaging
   • This gate is architectural coherence signal, not syntactic — it never returns fail and never ABORTs packaging by itself
   • Known limitation: the gate detects newly introduced Subs only; materially expanded Subs (existing Sub whose body changed substantially) are not detected — agent review of Source diff remains required when expansion is the kind of change in question 9-IDO. Import Dependency Ordering gate — run before any packaging when the batch contains 2 or more distinct objects:
   • Run & ..\scripts\Test-GeneXusBatchDependencyOrdering.ps1 -FrontFolder <pasta-da-frente> -CorpusFolder <ObjetosDaKbEmXml> -AsJson
   • not-applicable (fewer than 2 objects in the batch) → proceed normally
   • pass (single layer — no in-batch dependency edges detected) → proceed normally
   • alert (warn finding ido-multiple-layers) → present the suggested staging (layers in the finding) to the user; require explicit confirmation or justification before proceeding with single-bundle packaging
   • fail (fail finding ido-cycle-detected) → ABORT packaging: present the cycle (listed in the finding) to the user and require resolution before re-running
   • When the batch contains WorkWithForWeb objects, the script also emits an info finding with code ido-ww-detection-pending — the WorkWithForWeb → linked Transaction dependency detection is not yet wired into this script, even though the 9-WW gate itself now reads both structural forms. When this info finding is present and the batch mixes a WorkWithForWeb and its linked Transaction, the agent must verify ordering manually (read the linked Transaction from the WorkWithForWeb XML using the 9-WW form detection rules, then check whether that Transaction is in the batch) before packaging
   • Detection scope: (a) Procedure with bc:<X> → Transaction X when X is in the batch; (b) Procedure A → Procedure B when A calls B in its Source and B is new in this delta (not in ObjetosDaKbEmXml). Procedure → Procedure detection is best-effort scan of Source — false positives may be filtered by user review 9-FD. Front-Acervo drift gate — run before any packaging when ObjetosDaKbEmXml exists as the official corpus:
   • Run & ..\scripts\Test-GeneXusFrontAcervoDrift.ps1 -FrontFolder <pasta-da-frente> -AcervoFolder <ObjetosDaKbEmXml> -AsJson
   • not-applicable (no Object XMLs in the front) → proceed normally
   • pass (only info findings) → proceed normally
   • alert (one or more warn findings) → present each warn finding to the user; for front-equals-acervo confirm whether the lastUpdate was intentionally preserved (dependency re-sent without change) or needs updating; for lastupdate-unparseable resolve manually before packaging
   • fail (any fail finding) → ABORT packaging; report each finding and the corrective action:
     • front-older-than-acervo: the XML in the front has an older lastUpdate than the corresponding XML in the official corpus — use Copy-GeneXusAcervoToFront.ps1 (& ..\scripts\Copy-GeneXusAcervoToFront.ps1 -FrontFolder <pasta-da-frente> -AcervoFolder <ObjetosDaKbEmXml>) to copy the newer version from the corpus to the front with automatic lastUpdate bump, or copy manually and bump the lastUpdate; for initial seed of an existing corpus object that is not yet in the front, call the same script with explicit -ObjectList, -ObjectNames or -ObjectGuids; after resolution, re-run the 9-FD gate to confirm the drift is cleared. Pre-requisite for any populate/seed: the front folder must already exist, opened by New-GeneXusXpzFront.ps1 (wrapper New-*KbFront.ps1, -ReuseIfExists to resume) — do not create it manually; Copy-GeneXusAcervoToFront.ps1 and the gates only populate/inspect an existing front
     • front-object-type-drift: the front XML and official corpus XML have the same guid but different non-empty Object/@type after Trim() — ABORT and ask for a human decision. Do not auto-copy from the corpus or bump lastUpdate; first determine whether the correct object is the front XML, the corpus XML, or whether the generated/selected XML is contaminated. Public type-drift payload uses normalized objectGuid, matchBasis=guid, acervoPath, and message.
     • front-textual-fidelity-trim-removal-churn: the front XML removed inherited trailing whitespace at strong scale against a unique-GUID baseline — ABORT, rebuild the front XML from the corpus with Copy-GeneXusAcervoToFront.ps1 using an explicit target (-ObjectList, -ObjectNames, or -ObjectGuids), reapply only the functional delta, and re-run 9-FD. Explicit targets may overwrite an already edited/newer front copy; use them deliberately, preferably with -DryRun. Public blocking payload includes classification, whitespaceTrimPairCount, functionalChangedLineEstimate, acervoLineCount, and thresholds. This is partial mechanical protection only; do not treat it as a complete whitespace, reindentation, or EOL detector.
     • front-textual-fidelity-info: comparable UTF-8 text reading/decoding failed after a unique-GUID baseline was found — informational only; do not treat it as proof that whitespace fidelity was checked, and do not expect it for every case where textual comparison is skipped (for example, no baseline or ambiguous GUID). Public informational payload uses classification='not-applicable' and reason.
     • front-object-type-drift-ambiguous-acervo: the same normalized guid appears in more than one corpus XML — informational only in Phase 1, with matchBasis=guid-ambiguous and non-empty candidateAcervoPaths; do not choose an official Object/@type arbitrarily.
   • When using New-XpzImportPackage.ps1 (the front-based packaging wrapper), this gate always runs before the Python motor is invoked (fail-closed): -AcervoPath is optional and, when omitted, the canonical acervo <RepoRoot>/ObjetosDaKbEmXml is auto-resolved; with no acervo resolvable, packaging is blocked (the gate is never skipped by omission). The JSON field acervoResolvedBy reports explicit or convention. fail and alert both block automatic packaging, because warn findings require explicit acknowledgment or resolution before another packaging attempt
   • This gate does not replace 12 (check for improper local changes in ObjetosDaKbEmXml); 9-FD compares front vs. corpus content, while 12 detects direct edits in the read-only corpus
9. Check for improper local changes in ObjetosDaKbEmXml:

• If detected, treat this as an explicit process error
• Preserve those XMLs in ObjetosGeradosParaImportacaoNaKbNoGenexus, restore ObjetosDaKbEmXml to the official Git version, present a structured manifest of preserved items in the conversation, save it as a local file when incident traceability requires it, and ABORT packaging until the snapshot is sane
• If the target object has not yet returned from the KB by official export, keep working only from ObjetosGeradosParaImportacaoNaKbNoGenexus

13. Load 03-risco-e-decisao-por-tipo → assign risk level
14. Evaluate abort conditions:

• Risk is high/very high AND no comparable internal template exists → ABORT
• Type is not in the empirical corpus → ABORT
• User requests affirmation of import/build success → REFUSE, state limitation

15. Locate template:

• Transaction → use family F1–F6 from 05-transaction-familias-e-templates
• WebPanel → use closest family from 04-webpanel-familias-e-templates
• For WebPanel, declare the primary edit block before touching the XML and use only the adjacent blocks required by explicit functional dependency
• For DataProvider, declare the primary edit block before touching the XML and use only the adjacent blocks required by explicit functional dependency
• For API, declare the primary edit block before touching the XML and use only the adjacent blocks required by explicit functional dependency
• Simple report Procedure → use the canonical sanitized family from 05b-procedure-relatorio-familias-e-templates first when the case fits simple F2/F3 coverage and the selected block is marked as molde pronto
• Other types → use sanitized representative from 08-guia-para-agente-gpt materialization rules
• For simple report Procedure, escalate to comparable real XML only when the request falls outside the documented simple family, when the initial attempt plus one short structural corrective attempt already failed, or when KB-local dialect/localism appears
• For simple report Procedure, every output or handoff must label the basis used as exactly one of: molde sanitizado, XML real da KB atual, XML real de outra KB, or hipótese
• If the object has already returned from the KB via official XPZ processing, prefer the current XML in the official corpus over any older delta/import working copy when selecting the base for a new change
• Before cloning identity fields, classify the container from comparable corpus XML using Object/@parentType — never from the directory name in ObjetosDaKbEmXml, which varies across KBs. The canonical mapping of container GUIDs lives in scripts/gx-object-type-catalog.json (entries Folder for user-created containers, Module for GeneXus system/organizational containers, PackagedModule for installed modules, and RootModule for the virtual KB root that has no XML file in the acervo). Read the GUID from the corpus XML and look it up in the catalog; do NOT hardcode parentType GUIDs inline.

16. Apply conservative cloning:

• Preserve Object/@guid (new GUID only for new objects, never reuse existing object's GUID)
• Preserve parent, parentGuid, parentType, moduleGuid
• Keep all recurring Part types present, even if content is empty
• Do NOT invent Part types not present in the template
• Validate identity as a 6-field set before serializing: fullyQualifiedName, name, parent, parentGuid, parentType, moduleGuid
• For cloned or newly created objects based on an existing XML, validate expanded internal identity before packaging: Object/@name, fullyQualifiedName, guid, Name property, Description, Source, Rules/parm, internal calls, dependencies, and ObjectsIdentityMapping
• Search for residual template object name, description, GUID, and calls; classify each residual occurrence as intentional, necessary dependency, or clone error
• If any residual template identity remains unclassified, ABORT before packaging
• Do NOT derive fullyQualifiedName by concatenating parent + "." + name
• If parentType is 00000000-0000-0000-0000-000000000008 (Module/Folder), treat the container name as container only; it must appear in parent/parentGuid, not be promoted automatically into fullyQualifiedName
• If parentType is c88fffcd-b6f8-0000-8fec-00b5497e2117 (PackagedModule), allow module qualification in fullyQualifiedName only when comparable corpus objects of the same KB confirm that pattern
• For WebPanel, verify where each relevant property is actually persisted before editing: Conditions may live in its own Part, while ControlWhere, ControlBaseTable, ControlOrder, ControlUnique, PATTERN_ELEMENT_CUSTOM_PROPERTIES, and WebUserControlProperties often live inside serialized layout metadata; follow the operational rules in 02-regras-operacionais-e-runtime
• For WebPanel, treat serialized functional metadata as its own functional layer; do NOT collapse it into visual layout when planning or reviewing the delta
• For WebPanel, do NOT treat template defaults mentioning Conditions as proof that a real filter is materialized in the object
• For WebPanel, NEVER manually reconstruct serialized layout CDATA after truncated reading; extract the full block structurally or apply a surgical substitution on the full raw file while preserving the original serialized layout byte-for-byte outside the intended delta
• For WebPanel, name each justified block transition during review, for example events -> variables or layout -> serialized functional metadata
• For WebPanel, if the current reasoning no longer needs a new block, stop expanding; do NOT reopen the whole object by reflex
• For DataProvider, treat Output structure as its own functional layer; do NOT collapse return shape into a generic Source reading
• For DataProvider, if the delta touches collection vs simple, nested groups, node names, or return cardinality, classify Output structure as the primary edit block unless explicit evidence points elsewhere
• For DataProvider, if the delta depends on For each, base table, filters, or navigation ambiguity, open Navigation context only as an explicitly justified adjacent block
• For DataProvider, do NOT treat SDT, Procedure, BC, or Transaction dependency inventory by itself as proof of the output shape
• For DataProvider, name each justified block transition during review, for example Output structure -> Source or Source -> Navigation context
• For DataProvider, if the current reasoning no longer needs a new block, stop expanding; do NOT reopen the whole object by reflex
• For API, treat Service contract and Data contract as their own functional layers; do NOT collapse endpoint contract, response shape, and internal orchestration into a generic code reading
• For API, if the delta touches exposed method, endpoint, signature, published operation, input/output shape, or response structure, classify Service contract or Data contract as the primary edit block unless explicit evidence points elsewhere
• For API, if the delta depends on .Before/.After, internal validation, transformation, or orchestration flow, open Events and orchestration only as an explicitly justified adjacent block
• For API, do NOT treat Procedure, SDT, Domain, Transaction, EXO, or DataProvider dependency inventory by itself as proof of the published contract
• For API, name each justified block transition during review, for example Service contract -> Data contract or Events and orchestration -> Calls and dependencies
• For API, if the current reasoning no longer needs a new block, stop expanding; do NOT reopen the whole object by reflex
• Before generating a new delta for an object that already returned from the KB, compare any intermediate import/delta copy against the official corpus XML and rebase on the official corpus if the working copy is stale
• If a filter, business rule, or functional interpretation depends on a calculated or derived field, open the field formula/source and review the immediate chain of called procedures before defining the condition
• Do NOT conclude the semantic meaning of a calculated or derived field from its name, label, or mere XML presence
• If the change introduces or rewrites Source, classify every new operator, function, conversion, and string/numeric pattern introduced by the change
• Each introduced Source construct must be anchored by layer-1 methodological evidence from this XPZ trail: explicit rule, sanitized example, or documented template
• Local KB corpus may confirm or disambiguate the choice, but does NOT replace layer-1 methodological evidence
• If an essential Source construct is still justified only by plausibility, generic GeneXus memory, or isolated local corpus evidence, rewrite it using documented patterns or ABORT
• Before packaging an object that depends materially on Source, classify the result explicitly as well-formed XML and minimum Source sanity gate passed or failed
• If XML is well-formed but the minimum Source sanity gate failed, ABORT packaging
• Use lightweight automated Source sanity checks from the repository only as advisory support; a pass does not prove import/build success
• Recommended local check command when the XML file is already materialized: & ..\scripts\Test-GeneXusSourceSanity.ps1 -InputPath .\Objeto.xml
• Interpret the JSON result conservatively:
  • xmlWellFormed=false -> ABORT before any packaging discussion
• sourceSanityStatus=fail -> ABORT packaging and correct structural balance first
  • fail also covers the type-aware finding procedural-in-conditions: a Procedure with a non-empty Conditions part is rejected because Procedure has no Conditions filter (predicates live in For Each ... Where) and code there triggers src0055 on import; WebPanel/Prompt/Selection List, where Conditions is a legitimate filter, and Data Selector, which has its own Conditions, stay out
• sourceSanityStatus=warn with probablyImportable=true -> keep packaging blocked until each warning is either rewritten to a documented conservative form or explicitly justified as residual risk
• sourceSanityStatus=pass with xmlWellFormed=true -> proceed only to the next packaging gate; do NOT describe this as proof of import/build success
• If GeneXus Source is serialized inside CDATA, scan the saved block before packaging and ABORT if the literal code still contains XML entity spellings such as &, ", >, or < that should have remained raw code characters
• For report Procedure, classify each edited fragment before serialization as Source, Rules, or layout and reject any cross-layer mixture
• For simple report Procedure, load 05b-procedure-relatorio-familias-e-templates.md as a mandatory reference before generating from molde pronto; do NOT treat that read as optional
• For report Procedure, verify coherence between layout PrintBlock names and each print printBlock... reference in Source
• For report Procedure, if Source prints printBlockX, require a matching layout PrintBlock with coherent RPT_INTERNAL_NAME; if the pair is missing, ABORT before packaging
• For report Procedure, when cloning or adapting PrintBlock elements, verify that each RPT_INTERNAL_NAME value is unique across all sibling blocks in the layout Part; duplicate RPT_INTERNAL_NAME values across distinct blocks are a hard structural error — ABORT before packaging
• For report Procedure, treat the total layout width as a structural constant inherited from the source template or reference XML; do NOT invent or assume a default value — read it from the canonical template or cloned source; when the value is ambiguous, document the observed value explicitly in the packaging rationale before proceeding
• For report Procedure, if an import error points to invalid control, report block, or layout shape, inspect layout first before altering envelope

17. Apply envelope rules from 02-regras-operacionais-e-runtime:

• For delta of an existing object, prefer the package format with validated local precedent in the same KB trail before any generic preference
• Distinguish explicitly between embedded-object package under <Objects> and package using <FilePath> to external XML
• Consider local precedent strong only when object type, operation nature, and batch materialization style are compatible with the current case
• If precedent is only partial or analogical, justify it explicitly or ABORT for confirmation instead of extrapolating
• If the user has already signaled manual IDE import/testing, generate import_file.xml as soon as the delta is materially ready instead of postponing package creation
• Use import_file.xml as the primary package artifact for manual IDE import unless .xpz is explicitly required
• Wrap in <ExportFile> with <KMW>, <Source>, <Objects>, <Dependencies>
• Keep Source/@kb and Source/Version/@guid in valid GUID format
• Valid GUID format is not enough for headless import: when a local target KB identity is known, Source/@kb from the package or template must match that native KB. If it differs, treat the package as cross-KB, ABORT agent automation, and route the case to manual IDE evaluation per 02-regras-operacionais-e-runtime.md.
• Do NOT include special KB block unless explicitly documented as required

18. Set or preserve lastUpdate according to the batch-role classification:

• Classify each active XML as modified in this round or reused unchanged for mandatory dependency closure
• If any textual change was persisted in the final XML, classify the item as modified in this round
• Modified object → set lastUpdate to max(UtcNow + 60s, official-corpus lastUpdate + 60s); when available, prefer a local wrapper such as Get-*KbLastUpdate.ps1 or the shared engine scripts\Get-GeneXusXpzLastUpdate.ps1 -BaselineXmlPath <xml-do-acervo> to capture that value in one atomic call
• Unchanged dependency object → preserve the official lastUpdate from the official corpus XML
• If classification and materialized lastUpdate diverge → ABORT

19. Audit lastUpdate after every local write:

• After writing or rewriting an object XML, reopen the saved file and confirm the root lastUpdate
• If the object was actually modified, lastUpdate must be strictly fresher than the official corpus baseline and normally use the 60-second freshness margin
• If the object was not modified and is included only for mandatory dependency closure, preserve the official lastUpdate from the corpus XML
• Do NOT continue to packaging until the saved-file header has been checked

20. Before packaging, classify active XML roots and validate packaging hygiene:

• Object top-level → serialize under <Objects>
• Attribute top-level → serialize under <Attributes>
• Unsupported root type → ABORT or require explicit treatment
• For Transaction, every attribute referenced by Level/Attribute must exist as top-level Attribute under <Attributes> when the package is meant to create or complete those attributes in the target KB
• Do NOT serialize those required attributes as Domain or any other object type under <Objects>
• Canonical minimum valid package for a new Transaction:
  • <Objects> = the Transaction
  • <Attributes> = at minimum the PK and the description/display attribute used by the Transaction
  • <Dependencies> = only what the selected shape really requires
• TransactionOrObject, when present in a comparable export, may be included as an auxiliary object in <Objects>, but it does NOT replace the mandatory top-level <Attributes> required by the Transaction
• Validate UTF-8 without BOM on every active XML
• If BOM is present, remove it and register the correction
• Prefer package names in the form NomeCurto_GUID_YYYYMMDD_nn.import_file.xml
• NomeCurto must be short, human-readable, and semantically strong
• GUID and YYYYMMDD identify the front opening, not the package generation instant
• nn is only the short incremental round counter for that front, not semantic versioning
• Before writing the package, check whether the same front prefix NomeCurto_GUID_YYYYMMDD already has the same nn in PacotesGeradosParaImportacaoNaKbNoGenexus
• If the same front prefix already has that nn, ABORT instead of overwriting the existing file
• In that collision case, report the next free nn suggestion, but do NOT auto-increment or silently save under the suggested value
• Do NOT default to name-only, date-only/time-only, excessively long conversation descriptions, or always overwriting the same package name
• Produce or validate a manifest in the conversation containing at minimum: batch front or short description, batch origin, total XML count, Objects count, Attributes count, included files list or summary, lastUpdate applied or preserved, generated package, superseded package when present, and risk/pending notes
• Save that manifest as a file only when there is an incident involving ObjetosDaKbEmXml, package supersession that needs local traceability, explicit user request, or real need for future handoff outside the immediate conversation
• Validate the final envelope materialized inside import_file.xml, not only the source XML files
• Prefer a shared structured engine for import_file.xml assembly. Use scripts\Build-GeneXusImportFileEnvelope.ps1 for direct object XML inputs and a validated template package, with mandatory -AcervoPath <ObjetosDaKbEmXml> and -ModifiedObjectNames or -ModifiedObjectGuids for objects actually modified in the round; that helper clones KMW/Source/Dependencies/ObjectsIdentityMapping from the template, clones top-level Attributes from the template when no explicit -TopLevelAttributesXmlPaths were passed, embeds each object via ImportNode (which guarantees no inner <?xml ...?> is carried over), runs the deterministic collision gate (Test-XpzPackageCollision.ps1) before any write so a colliding _nn aborts the script with zero bytes materialized, checks front-vs-acervo coherence (lastUpdate and Object/@type by same guid) before serializing, and runs the envelope gate automatically before delivery; it does not cover strong global trim in this version. Use the safe wrapper scripts\New-XpzImportPackage.ps1 when the package source is a named front under ObjetosGeradosParaImportacaoNaKbNoGenexus; its 9-FD gate also blocks strong removal of inherited trailing whitespace by unique-GUID baseline and may emit informational front-textual-fidelity-info only when that baseline exists but comparable UTF-8 text reading/decoding failed, with partial protection only, not a complete whitespace/reindentation/EOL detector. Pass -TemplatePackagePath for mixed/complex packages so the front-based engine clones a comparable real envelope instead of relying on metadata-only minimal envelope, including top-level Attributes from the template when the front does not provide explicit Attribute roots. -TemplatePackagePath may point to .import_file.xml/XML or to a .xpz that contains an ExportFile XML.
• When passing -TemplatePackagePath, ensure the chosen template is comparable to the current case: same KB origin, similar package nature (full vs surgical delta vs migration), and import-flow context aligned with current intent. Cloning from a non-comparable template can contaminate the new package with Dependencies and ObjectsIdentityMapping bindings from an unrelated context — that is a worse outcome than the metadata-derived minimal envelope. If a comparable template is not available, prefer the minimal envelope (omit -TemplatePackagePath) and accept the engine's envelope-minimo warning explicitly in the packaging rationale. When local evidence shows that the active import flow expects a full IDE-style ExportFile envelope, prefer a comparable IDE-exported template regardless of GeneXus major version; do not encode this as a GeneXus 16-only rule. When the parallel folder documents a known-good reference package path (e.g., in its local AGENTS.md), use that path as default candidate for -TemplatePackagePath; verify comparability before passing it.
• ObjetosGeradosParaImportacaoNaKbNoGenexus and PacotesGeradosParaImportacaoNaKbNoGenexus are agent-managed work areas, not user drop folders. If an example/reference/template XML appears inside the active front, including root-valid Object/Attribute XML explicitly marked as reference material, or if any unsupported XML appears there, ABORT packaging and move the reference outside the generated-objects area only with explicit user approval and traceability; do not silently ignore it.
• Treat manual text-level assembly of import_file.xml (string concatenation of object XMLs into the envelope) as a discouraged fallback subject to the NEVER constraint above (CONSTRAINTS): allowed only when both shared engines are demonstrably unusable AND the user has explicitly acknowledged the exception
• When the helper rejects the package, the candidate file is preserved as <OutputPath>.rejected.<A..Z> for forensic inspection; do NOT rename it back to the canonical *.import_file.xml to retry — fix the input and rerun
• Run scripts\Test-GeneXusImportFileEnvelope.ps1 -InputPath <package> after writing the final import_file.xml; the gate emits JSON by default. For Panel with a comparable package/object available, also pass -PanelReferencePath <template-or-object> so a confirmed level id/layout id pair is information rather than an unresolved warning. Treat não apto para prosseguir as a hard stop before delivery. Build-GeneXusImportFileEnvelope.ps1 already calls this canonical gate and passes its -TemplatePackagePath as the Panel reference; New-XpzImportPackage.ps1 performs its own internal envelope validation, so the canonical gate must still be run explicitly before delivery unless it has already been run after package assembly.
• When the user has explicitly authorized headless import in the same session and Test-GeneXusImportFileEnvelope.ps1 returned apto para prosseguir, do not treat packaging as the end of the round: hand off to xpz-msbuild-import-export and execute Invoke-GeneXusXpzImport.ps1 per that skill (-StartWatcher and -MonitorLogPath mandatory). Envelope validation alone is not the final step.
• NEVER copy objects from an exported .xpz or external package into the current front's import_file.xml without classifying each item as requested change, necessary auxiliary change, or extra unrequested change; any extra unrequested change blocks packaging until explicitly resolved with the user — do not silently absorb export bloat (platform modules and similar extras can trigger very long builds).