Ergon Archon Screen Discovery
When available, consult the derived praxis-screen-discovery-matrix before
starting discovery to choose comparable pilots and identify known contracts or
runtime gaps. Regenerate it after discovery changes the operation inventory or
phase gate. It is an index only: XML/runtime evidence, the phase gate and the
canonical Praxis resource contract decide discovery conclusions.
Use this skill to turn an exploratory Ergon/Archon screen investigation into a reproducible migration package. Prefer evidence-backed conclusions over naming conventions. When coordinating a multi-phase migration, use ergon-migration-orchestration first to verify phase gates and artifact handoff.
Rule-intent handoff
Do not answer a Parte 2 request for an active customer customization from XML,
JavaScript, onChanged, field validation or another client-side screen rule
merely because those sources are easy to locate. A short prompt such as
“identifique uma customização cliente ativa na escrita de ” carries an
intent plus identifier: resolve the existing Parte 1 write handoff and route to
ergon-rule-migration-orchestration. You must use that skill before issuing
any active/inactive conclusion; do not finish the request inside screen
discovery. Screen discovery may contribute the
operation and DB-backed route, but it must not substitute a UI rule for the
requested customer-specific server-side rule.
If both a client-side validation and an Oracle/HADES customer extension exist,
preserve both as distinct origins and let the rule workflow classify the
requested one. Do not ask the user to spell out HADES flags, owners, EP names,
packages or source ranges that the factory is expected to discover.
For developer onboarding and day-to-day execution, use developer-quickstart.md. For repeatable starts, use prompt-template.md. For didactic PT-BR user guidance and ready-to-use prompts by reading/discovery scenario, use read-prompt-examples.md. For team handoff review, use handoff-review-checklist.md. For database access provisioning, use codex-oracle-access.md. For authenticated browser-session capture, use codex-browser-runtime-capture.md and runtime-capture-form-template.md. For Cronos XML source-of-truth decisions, use cronos-source-of-truth-template.md. For legacy documentation discovery, use legacy-docs-discovery.md. For component-to-API inventory, use component-lineage-matrix-template.md. For read endpoint parity gates, use read-parity-matrix-template.md. For Java/API package-state parity, use java-oracle-session-context.md. For API endpoint design, use api-design-patterns.md, lib-ui-fieldspec-api.md, and java-api-implementation-playbook.md. For a filled read-first frequency API model, use example-ergadm00189-api-contract.md. For architecture-level write patterns, use archon-write-patterns.md. For write behavior and write deferral, use write-risk-template.md, write-risk-detail-template.sql, and write-api-handoff-template.md. For deciding whether a screen can move to API implementation, use closure-checklist-template.md.
Platform Governance
Apply the root migration AGENTS.md while producing discovery artifacts. The
screen discovery phase must identify whether a finding belongs to the Ergon
host, praxis-metadata-starter, praxis-config-starter, praxis-ui-angular,
or another owner.
When discovery finds missing or weak support for _links, /actions,
/surfaces, /capabilities, /schemas/filtered, x-ui, option sources, or
Angular runtime behavior, do not prescribe an Ergon-local workaround as the
default. First classify the need as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado,
suportado-parcialmente, or lacuna-real-de-contrato. Only real contract
gaps should become Praxis Platform Follow-up.
Keep HADES, SQL, ROWID, empresa, usuario, perfil, package names, and session
context as evidence for backend implementation, not public DTO/schema/URL/x-ui
contract.
Operating Principle
Investigate in this order unless the user gives a stronger reason to change it:
- Open the legacy screen and observe the actual user workflow.
- Find the Archon XML/debug definition for the same screen.
- Extract screen SQL, component names, bind tokens, links, filters, page size, hidden fields, and default values from browser/XML evidence.
- Use the extracted SQL objects as the seed list for Oracle metadata discovery.
- Expand Oracle lineage, security, grants, triggers, keys, and write risks only after the screen evidence is anchored.
- Close write behavior as either API-ready or explicitly blocked/deferred with evidence before claiming read/API readiness.
Do not start from broad Oracle scans or name matching when browser/XML evidence is available. The screen XML and runtime SQL are the primary evidence for what the user-facing workflow actually uses.
Standard Operation Inventory
Every Ergon/Archon screen discovery must produce or update operation-inventory.md. Start from the standard framework operations and then mark each one with one of the allowed states: Implemented, Ready, Candidate, Blocked, Deferred, or Not present.
Consultar/listar: default load, visible filters, pagination, sorting, company/user scope, empty state.
Ler detalhe: row selection, detail form/panel, nested grids, public key, internal locators.
Novo/Salvar: create button, edit state, defaults, required fields, validation messages, P_OPER/routine/table route, success side effects.
Editar/Salvar: editable fields, immutable keys, changed-field payload, validation messages, side effects.
Apagar: delete/anulation button, confirmation text, permission and dependency blockers.
Duplicar: copied/defaulted values, new key fields, whether it reuses create route.
Cancelar: no-op behavior from create/edit/duplicate modes.
Documentos legais: tab/block/component, read source, write route when editable, PONTLEI or equivalent link key.
Publicacoes/atos, Pendencias, and other related framework blocks when visible in XML, browser, or table-rule side effects.
For each row, record: browser evidence, XML/component evidence, Oracle/source evidence, candidate endpoint, FieldSpec/platform mapping, current backend state, parity state, and exact next check. Do not collapse Novo, Editar, Apagar, Duplicar, and Documentos legais into a generic "writes pending" note.
Use this FieldSpec mapping baseline when filling operation-inventory.md:
Consultar/listar: POST /<resource>/filter backed by BaseResourceService.filterWithIncludeIds.
Ler detalhe: GET /<resource>/{id} backed by BaseResourceService.findById; GET /by-ids when the UI needs selected-row reloads.
- Lookups/options:
POST /options/filter, GET /options/by-ids, OptionDTO, and @UISchema(endpoint/filterField/sortField/optionsPageSize).
Novo/Salvar: POST /<resource> backed by save only after write gates close; otherwise blocked/deferred.
Editar/Salvar: PUT /<resource>/{id} backed by update only after update payload and side effects close.
Apagar: DELETE /<resource>/{id} backed by deleteById; batch delete is a separate explicit decision.
Duplicar: POST /<resource>/{id}/duplicate-draft through DuplicateDraftResourceService.duplicateDraft, then normal create on save.
Cancelar: no backend mutation; prove UI state reset/no write.
Documentos legais, Publicacoes/atos, and Pendencias: separate related resources/workflows unless runtime/XML proves they are fields of the main resource.
For Ergon screens that depend on HADES.FLAG_PACK, note that the FieldSpec endpoint shape stays standard while implementation must run context setup/cleanup on the same Oracle connection through the shared legacy bridge.
New Platform Reuse Discovery
After the legacy operation inventory is anchored, search the target Java/OMS modules before creating new API candidates. Produce platform-reuse-inventory.md with one row per operation/resource and a decision: reuse, extend, create, block, defer, or not-api.
Inspect at minimum:
- endpoint/path constants and OpenAPI groups;
- controllers, resource services, DTOs, FilterDTOs, mappers, repositories, entities, and tests;
- resources already migrated for related screens or shared lookups/options;
docs/migracao/platform-option-sources.md generated by tools/migration-factory/export-platform-option-sources.ps1 -Force when the workspace has that helper, plus docs/migracao/options-lov-promotion-status.md, before treating a LOV/option as new or blocked; record generatedAt, covered property files/modules, and promotion status source so a missing source is not inferred from stale or incomplete coverage;
- shared services for legacy context, authorization, legal documents, publications, pending flows, and FieldSpec schemas;
- semantic gaps between the existing new-platform resource and the legacy screen behavior.
If an existing resource matches the legacy operation, record the exact path/class and prefer reuse or extension. Do not propose a duplicate endpoint unless the incompatibility is explicit.
For LOV/options, record PLATFORM_OPTION_SOURCE_RESOLVED when sourceKey, dependencies, selected-value reload, and visible semantics match; PLATFORM_OPTION_SOURCE_REVIEW_REQUIRED when an existing source is close but semantically incomplete; and PLATFORM_OPTION_SOURCE_BACKLOG_REQUIRED only when no configured/promoted source fits and the target microservice/module was covered by the inventory. For dependent sources, selected-value reload must be proven separately from filtering: either the ID is self-contained for GET .../by-ids, or the contextual POST .../by-ids path is implemented and consumed with the required public dependencies. Treat review-required as an extend decision by default; use block only when the gap prevents the current screen contract.
Phase Boundary
Use this as phases 1 and 1.5 of the migration:
ergon-archon-screen-discovery discovers and closes the screen boundary: browser workflow, XML/runtime SQL, Oracle lineage, keys, scope, authorization, read API candidates, and write risk/handoff.
- It may produce a candidate read API contract, but
ergon-archon-read-api-migration owns final read API design/implementation.
- Write endpoints remain
Blocked or Deferred unless write behavior is fully closed.
- When write remains blocked/deferred, create
write-risk.md and write-api-handoff.md so ergon-archon-write-api-migration can run after the read API phase.
- Before leaving phase 1, close the screen's write surface: visible actions, XML/runtime action source, candidate routines/tables, payload evidence or explicit gap, key/ROWID strategy, session context, and blockers.
- Before handing off to
ergon-archon-read-api-migration, create read-parity-matrix.md from read-parity-matrix-template.md. Do not mark the read phase as closed if list/detail/options/related read endpoints lack explicit parity status and gaps.
- Before handing off to read/write API skills, produce
platform-reuse-inventory.md or mark reuse discovery blocked with exact missing repository/module access.
- Use
ergon-table-rule-audit only for table-level write-rule closure, normally after the read API phase and after target tables are known.
If the user asks for write implementation before these artifacts exist, keep the work in discovery mode and close the missing handoff evidence first.
Discovery Gates
Before starting Phase 1, require an entry gate. docs/migracao/<SCREEN>/migration-plan.md and phase-0-execution-gate.md must exist, the target screen code must be explicit, and Fase 0 must recommend ergon-archon-screen-discovery. If these are missing, do not create a partial discovery package by hand; return to ergon-migration-orchestration and the canonical roadmap entry point.
At the start of discovery, record the evidence plan: browser/runtime availability, runtime XML/local XML/HADES source plan, docs-legado paths to search, Oracle access status, expected factory helpers, and whether the intended slice is quick discovery, full discovery, or API migration. Missing browser, Oracle, XML export, or docs access is not fatal by itself, but it must become an explicit Blocked, Partial, or Unavailable status in the gate and artifacts.
Before handing off to any API implementation skill, require an exit gate. The package must contain phase-1-execution-gate.md, closure-checklist.md, component-lineage-matrix.md, operation-inventory.md, read-parity-matrix.md, Oracle/HADES confirmation or blocked rerun artifacts, and a candidate api-contract.md when API migration is in scope. A gate may be Ready for read API, Read handoff ready; write deferred, Ready for write API, Blocked, or Deferred; it must not be implied by the presence of Markdown files alone.
Legacy documentation under docs-legado is primary evidence for business meaning, historical model context, related flows, and parity scenarios, but it is not implementation proof by itself. Promote a doc fact into API readiness only after it is tied to browser/runtime, XML/debug, local source, Oracle metadata, or an explicit accepted deferral.
Legacy System Access
Default demo entry point:
http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm_mnu001.tp
Use the authenticated browser surface that actually has the session. Prefer the Codex in-app browser when the user has it open or can log in interactively. Use Chrome when the user asks for Chrome, the authenticated session is already in Chrome, or the user's profile/extensions are needed. Use Playwright only as a fallback for repeatable screenshots or scripted smoke checks after the browser-session path is understood.
Legacy Archon pages can have unstable DOM locators. If DOM inspection hangs or returns unreliable results, use screenshots plus coordinate/CUA-style actions to operate the page, and record the limitation in browser-runtime.md. Do not downgrade confirmed visible behavior just because DOM automation is weak.
If credentials are provided in the conversation, use them only for the active private session, but do not write them into reports, SQL files, commits, logs, screenshots, command history artifacts, or generated files. If credentials need to be reused locally, prefer environment variables or a private password manager outside the repository.
After login:
- Confirm the authenticated Home/Menu screen: visible user, visible company, current URL path, and current menu transaction.
- Click or focus the search field labeled like
Buscar transacao.
- Search for the target page code first, for example
ERGadm00033, ERGadm00034, or ERGadm00189. Search by visible title only if the code does not return a result.
- Open the matched page from the search result instead of guessing the final URL.
- Record the selected result text, navigation path, visible title, module/breadcrumb, and final URL path.
- Exercise the visible workflow: default load, company selector, search/filter fields, tabs, links, action buttons, pagination, and detail navigation.
- Capture observed parameters and changed SQL behavior after each interaction.
If the search does not find the transaction, try the visible menu/area path and record each clicked label. If neither search nor menu opens the screen, mark navigation as Blocked - screen not reachable for current user.
If login or browser access is unavailable, continue from local XML/source and mark Observed as Missing or Partial in the gates.
Runtime XML Export Gate
For Cronos/Archon .tp transactions, always try the matching .xml runtime export before treating local XML as final:
/<Application>/<Module>/<Transaction>.xml
Example: http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm00034.xml.
This route is handled by Cronos export code, requires an authenticated user with layout-export permission (privilegiado or alteraLayout), retrieves the runtime descriptor, and serializes it through TransactionXmlWriter. It is not merely a static file read.
If tools/migration-factory/download-runtime-xml.ps1 exists in the repository, run it before any manual extraction from the browser viewer. It is the preferred path because it saves the raw response only after XML parser validation and writes sanitized evidence. Pass credentials only through a pre-created PSCredential or pre-existing env vars; do not put secrets in the command.
Required behavior:
- Use credentials only for the active private session; never write them to artifacts, logs, SQL, commits, screenshots, command history, or prompt templates.
- Open the
.tp route to prove the runtime screen is reachable for the current user.
- Download the
.xml route for the same application/module/transaction. If browser JavaScript cannot read HttpOnly cookies or lacks fetch/XMLHttpRequest, do not stop there: when the login page exposes a form, parse the actual <form action> and resolve it against the response URL. Example: action="/login" under /Ergon/Administracao/<SCREEN>.tp resolves to http://host/login, not /Ergon/login. Use an in-memory HTTP session/cookie container to request .tp, submit the resolved login action with the observed form fields, then request .xml. Keep credentials and cookies only in memory.
- Save the exported XML under
docs/migracao/<SCREEN>/runtime/<SCREEN>.authenticated.xml or docs/migracao/<SCREEN>/runtime-exported-xml/<SCREEN>.xml only when it contains no credentials or sensitive runtime data beyond screen metadata and the saved file parses as XML.
- Record URL, HTTP status, redirect/login status, content type, byte size, SHA-256 hash, parser result, timestamp, and non-sensitive user/session context.
- Compare exported XML against local product XML under
docs-legado/**/crodata/trans/<Module>/<Transaction>.xml.
- Produce or update
cronos-source-of-truth.md with one of: RUNTIME_EXPORTED_XML_MATCH, RUNTIME_EXPORTED_XML_DIVERGED_FROM_LOCAL, RUNTIME_XML_EXPORT_FORBIDDEN, RUNTIME_XML_EXPORT_AUTH_BLOCKED, RUNTIME_XML_EXPORT_NOT_FOUND, or LOCAL_XML_ONLY_UNCONFIRMED. This artifact is mandatory whenever a runtime XML, local XML, HADES/stored XML, or XML-export residual exists. If HADES/Oracle is unavailable, still create the file and mark the source-of-truth decision Blocked or Partial; do not leave the decision only inside investigation.md.
Never use document.documentElement.outerHTML from Chromium's XML viewer as the raw XML export; it can capture the viewer page instead of the original resource. If the raw XML cannot be saved, record the exact attempted methods and residual such as XML_RAW_EXPORT_NOT_SAVED.
Do not treat copied/rendered text from Chromium's XML viewer as raw XML unless an XML parser accepts the saved file. The viewer can display escaped XML attribute content as literal markup, producing invalid XML such as attributes containing raw <div ...>. If parsing fails, classify the file as RUNTIME_XML_BROWSER_TEXT_INVALID; use it only as diagnostic evidence and continue from parser-valid local XML, raw HTTP export, or HADES/Cronos source.
Never place credential literals in shell commands, generated scripts, report snippets, or command transcripts. Prefer a local secrets/env file, environment variables, or an already-authenticated browser session. If no safe non-recording credential path exists, ask the user for one before running an HTTP login from the shell.
When credentials exist only in the active conversation/session, prefer logging in through the authenticated browser surface over embedding credentials in shell. If browser automation cannot safely submit the login, ask the user to log in manually and continue from that session. Even without submitting credentials, parse and record sanitized login mechanics from the login HTML: resolved form action, method, field names, HTTP status, and issued cookie names only.
Use exported runtime XML as the primary structural source when it exists and diverges from local XML. Still capture browser/runtime evidence for SQL behavior, binds, permissions, action availability, write payloads, and dynamic controller behavior; exported XML alone does not close API parity.
Cronos Bind And Scope Resolution
For Cronos/Archon screens, do not treat Chrome/browser automation as the only
way to close bind semantics. When the open question is bind order, lookup source,
special selector values, or company/session scope, first combine parser-valid XML
and Oracle metadata:
- Read
sqlParameters and bind order from the runtime XML or from the accepted
source in cronos-source-of-truth.md.
- Read the SQL predicate where the bind is applied, for example
VALOR = ?.
- Locate the reused component definition or an equivalent screen component that
defines the same control.
- Resolve the combo/searchbox source through Oracle metadata, view text,
dependencies, synonyms, or package/function source.
- Save the read-only Oracle output under
docs/migracao/<SCREEN>/oracle-results/.
- Classify the bind as public filter, server-side scope, constant bind,
parent-row context, or internal runtime parameter.
Example pattern already proven in ERGadm00034: component/HADadm_blk003
exposes drpSelecEmpresa; equivalent screens define it with
select valor, descr from SELEC_COMBO_EMPRESA_VW order by valor; Oracle view
text confirms -1 = all companies, -2 = no company, and
flag_pack.get_empresa = current company. That means VALOR is internal
company/query-mode scope, not a public FilterDTO, schema, URL, OptionDTO.extra,
or x-ui field when a functional key exists.
Public Identity Must Follow The Effective Legacy Query
Never infer a composite or opaque public id merely because a legacy view
contains duplicate domain keys. First distinguish view fan-out from entity
identity:
- prove the base-table PK/UK and its projection through the view;
- reconstruct the exact list/detail query used by the component;
- apply server-side scope/session binds under the same Oracle connection;
- test key uniqueness in that effective resource slice;
- confirm how child components and legacy operations identify the selected row.
The unscoped view count is diagnostic only. If the domain key is unique in the
effective slice, expose that key and keep company, user, HADES state, VALOR,
ROWID, and equivalent locators internal. If duplicates remain, determine
whether they are projections of the same entity or genuinely distinct public
resources before considering normalization, a composite key, or an opaque id.
Record candidate_public_key_unique_in_effective_scope when the effective probe
proves one selected-row match and key uniqueness. Record
blocked_effective_scope_key_uniqueness_not_proven when that probe has not run
or its same-connection scope is not reproducible; do not convert uncertainty
into an opaque-token design.
Use docs/migracao/phase1-cronos-bind-resolution-standard.md when present. If
XML plus Oracle metadata closes the semantics and no browser evidence
contradicts it, record BIND_SEMANTICS_CLOSED_BY_XML_ORACLE or equivalent in
the gate instead of blocking only because Chrome/browser automation is
unavailable. Browser/runtime evidence is still required for visible workflow,
action availability, messages, write payloads, restricted-user behavior, and
final legacy/API parity.
Cronos RecordPanel Write Payload Resolution
For standard Cronos/Archon write panels, do not make browser navigation the first
or only path to close create/update payloads. If XML shows
component/recordPanelEdit with dataTable and without rotina,
insertMethod, updateMethod, or deleteMethod, resolve the payload from
parser-valid XML plus the local Cronos framework source before asking the
developer to operate the browser.
Required source-derived check:
- Locate the
recordPanelEdit component and its dataTable.
- Extract sibling/child
component/editField/* controls in layout order:
field, fieldTarget, caption, dataType, required, validators,
initialValue, valueProperty, displayProperty, and lookup SQL/options.
- Confirm in Cronos source that
RecordPanelEditImpl dispatches dataTable to
createManagerDescription().
- Confirm
ManagerDescriptionParameters uses _op for operation, _p_ for
proposed values, _o_ for original values, and _q_p_ for query/reload
values.
- Confirm
ManagerTableParametersImpl and AbstractTableDescription generate
table INSERT, UPDATE ... WHERE PK, and DELETE ... WHERE PK.
- Confirm
ManagerDescriptionImpl executes the generated Oracle SQL on the
application connection and reloads rows by internal rowid/query description.
When tools/migration-factory/new-cronos-recordpanel-write-payload.ps1 exists,
run it with -Strict and save the generated Markdown/JSON under
docs/migracao/<SCREEN>/factory/. A passing result may close create/update
payload discovery as SOURCE_DERIVED_PAYLOAD_READY_FOR_DB_PROBE.
This source-derived payload replaces browser payload capture for the standard
recordPanelEdit + dataTable pattern. Browser remains useful for visible
success/error messages, action availability, duplicate defaults, permissions,
cancel/no-op behavior, and final UI parity, but it should not block payload
closure when XML + Cronos source already prove the route.
Assisted Codex Browser Session
When the in-app browser is available, ask the developer to log in once if needed, then operate from the authenticated page. For direct URLs such as:
http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm00189.tp
record the page as Browser access status: Partial as soon as the authenticated screen is visible, even before every workflow is exercised. Then complete the observation by clicking through the visible UI:
- Confirm final URL, title, module, and whether the menu/search path also finds the page.
- Inspect frames, popups, debug panels, XML/debug buttons, network/runtime SQL panels, and hidden fields exposed by the legacy UI.
- Prefer direct browser observation for dynamic behavior that automation often misses: enabled/disabled actions, popup navigation, row selection, tab lazy loading, validation messages, and session-specific authorization.
- Save only concise evidence. Do not dump full page HTML, screenshots with sensitive data, or credential-bearing logs into the migration package.
- If Codex cannot programmatically inspect the in-app browser in the current environment, have the developer keep the page open and use browser-visible facts they provide as
CONFIRMED_RUNTIME_MANUAL; do not upgrade SQL/bind behavior to CONFIRMED_RUNTIME until Codex or a captured debug artifact verifies it.
Create or update docs/migracao/<SCREEN>/browser-runtime.md using codex-browser-runtime-capture.md. Also create runtime-capture-form.md from runtime-capture-form-template.md when Codex cannot inspect the browser DOM directly and the developer must relay visible/debug facts. browser-runtime.md is the working runtime notebook; summarize only stable findings back into investigation.md.
For Phase 1 validation before developer handoff, runtime-capture-form.md is not a substitute for executed runtime evidence. If default load, runtime bind values, page size, selected-row/public-key proof, visible action state, or representative non-empty fixture/context are missing, close Phase 1 as Blocked; do not mark it Ready for next phase or Ready for next phase with adjustments.
When the workspace provides docs/migracao/phase1-scope-authorization-standard.md, use it as the Phase 1 scope/authorization contract. The factory workbook should record phase1-scope-authorization-v2-bridge when the screen is an API-only Ergon/HADES bridge. allowed-default-context can close only with authenticated browser default load, non-empty fixture, selected row, public-key correlation, and same-connection Ergon/HADES Oracle context. For API-only screens governed by ergon-hades-security-starter and ergon-legacy-bridge, company-scoped-context and restricted-user-context close by the shared bridge/security contract and must not block each screen individually. Reopen them as blocking only when the screen bypasses HadesLegacyAccessGuard/equivalent, bypasses ErgonLegacyExecutor/equivalent, exposes company/user/profile/security context publicly, or implements custom security outside HADES. When the factory provides new-phase1-scope-authorization-decision-pack.ps1, generate its Markdown/JSON pack only for genuinely open scope cases; the pack requests owner decisions but does not close Phase 1 by itself. Do not turn company, user, profile, permission, or session binds into public FilterDTO/schema/URL/option/x-ui fields.
Workflow
- Identify the target screen code, URL, title, module, and user-visible workflow.
- Open the default legacy entry point when no direct URL is known, log in using credentials provided by the user for the active session, and locate the screen through the page/menu search field.
- Run the Runtime XML Export Gate for the matching
.xml route. If export succeeds, compare it with local product XML and use the runtime export as the primary structural source when it diverges. If export is blocked, record the blocker and continue with lower confidence.
- Inspect the running screen with the Codex in-app browser when available, or Chrome when the user's Chrome profile is required. Capture visible grids, tabs, actions, links to related screens, debug tree nodes, XML/debug
sqlSelect, sqlParameters, page size, filters, hidden fields, and observed bind values. If browser inspection is unavailable, continue from local XML/source and mark browser evidence as missing or manual-only.
- Inspect local legacy artifacts when present, especially
docs-legado/**/<SCREEN>.xml, view scripts, Java services, DTOs, and resource classes. Treat XML sqlSelect, sqlParameters, component ids, links, and filter bindings as an initial source for Oracle seed objects only after classifying runtime export availability.
- Inspect the legacy architecture/documentation tree when
docs-legado/v7x is available using legacy-docs-discovery.md. This tree has known evidence layers: Archon XML/controllers under java, local DDL/source under aps, Enterprise Architect exports under EA, RoboHelp model/reference archives under help, functional/technical specs under docs/Interno, workflow assets under workflow, and older Forms/Reports assets under forms and reports. Use these sources for business meaning, candidate parity cases, model context, and related-flow discovery; do not let documentation override browser/XML/Oracle evidence.
- Build a narrow seed list from browser/XML SQL before querying Oracle. Include screen views, lookup views, linked-screen views, packages/functions referenced by SQL, and objects introduced by related flows.
- Query Oracle metadata using oracle-queries.md. Treat
ERGON and HADES as defaults, not universal owners. Resolve synonyms, expand views recursively, inspect columns, constraints, indexes, triggers, grants, package arguments, source references, updatable columns, and write risks.
- Classify every object by role and confidence. Do not promote structural matches to confirmed objects without evidence.
- If screen SQL, views, helpers, triggers, or packages depend on Oracle package state such as
HADES.FLAG_PACK, document the Java same-connection context strategy using java-oracle-session-context.md. Do this before marking any Java/API contract as ready.
- Produce or update read-only Oracle confirmation SQL from oracle-confirmation-template.md when Oracle access is available or when follow-up confirmation is needed. When the repository has
tools/migration-factory/new-phase1-oracle-sql.ps1 and factory/extraction.json exists, use that generator before writing any manual Oracle/HADES SQL. It standardizes oracle-confirmation.sql and hades-registry.sql from XML seeds, preserves owner/package/subprogram identity, avoids known dictionary mistakes such as ALL_PROCEDURES.STATUS, expands view/physical lineage, reports owner collisions, covers HADES registry/access/menu/stored-resource candidates, and adds minimal non-empty smoke probes for read/view seeds. Manual SQL is allowed only as a supplemental artifact with the exact reason recorded in the gate. A Phase 1 package must include both object confirmation coverage and HADES registry coverage, either in oracle-confirmation.sql plus hades-registry.sql, or in one clearly sectioned SQL file. Use the executed outputs to fill the component-to-API matrix and candidate API contract facts: DTO fields, FilterDTOs, options, keys, scope, authorization, session context, related resources, and blocked/deferred writes. If execution fails, save a sanitized blocked note under oracle-results/ and keep all Oracle/HADES findings below CONFIRMED_ORACLE_METADATA. Before closing the gate, scan every referenced Oracle/tool output for ORA-, SP2-, TNS-, ERROR:, Exception, and IllegalArgumentException; a corrected supplemental SQL may supersede a failed statement only when the gate explicitly records the failed output and the replacement evidence.
- Create or update
read-parity-matrix.md from read-parity-matrix-template.md. For every read endpoint candidate, record the legacy component, Oracle source, Java/API source if it exists, key strategy, filters/binds, paging/sort, options behavior, HTTP/API execution status, and the exact remaining gap. A read API can be "implemented" and still not be "parity closed".
- When the XML/browser shows create, edit, delete, duplicate, pending, publication, legal-document behavior, or
recordPanelEdit with a db:* routine, read archon-write-patterns.md, then create write-risk.md from write-risk-template.md and a focused write-risk-detail.sql from write-risk-detail-template.sql. Use exact routines/tables/triggers from XML/runtime evidence; avoid broad table-name source searches. If the screen is closed as Ready for read API or receives a read-first implementation while write remains blocked/deferred, create write-api-handoff.md from write-api-handoff-template.md.
- Before starting Phase 3 write design, close write payloads for every visible write action in scope. For standard Cronos
recordPanelEdit + dataTable, prefer the source-derived XML + Cronos framework path above and then require a controlled DB probe. For rotina/object-method/custom actions, or when XML/source does not prove the route, capture runtime write payloads for Novo, Editar, Apagar, Duplicar, Salvar, Cancelar, legal-document actions, publication actions, pending actions, and any screen-specific business action. Record UI state before/after click, confirmation dialogs, hidden keys such as ROWID_REG, operation selector values, selected public id, P_MENS, routine arguments, legal-document/publication/pending fields, changed debug/network request, and observed validation messages. If neither source-derived payload nor runtime payload can be captured, mark the operation Blocked or Deferred with the exact next XML/source/browser/debug step; do not leave operation-inventory.md with a generic Unknown backend state and do not infer payloads from PL/SQL signatures alone.
- Use gates before finalizing:
Observed, Resolved, Expanded, Read-parity planned/executed, Write-risk checked, False-positive checked, Confirmation SQL complete, Session-context checked, and, for Java work, API-ready.
- Produce the investigation report using investigation-template.md.
- If the user is planning Java migration, read api-design-patterns.md, lib-ui-fieldspec-api.md, and java-api-implementation-playbook.md, then produce the API contract using api-migration-template.md. Keep endpoints as
Candidate, Blocked, or Deferred until keys, scope, authorization, session context, runtime binds, FieldSpec contract, read parity plan, and write boundaries are closed.
- Load example-ergadm00033-findings.md only when the target is ERGadm00033/ERGadm00034 or when the user explicitly asks for that example.
- Load example-ergadm00189-findings.md only when the target is ERGadm00189 or when the user explicitly asks for that example. Load example-ergadm00189-api-contract.md when drafting or validating a read-first frequency API contract.
- Load case-review-ergadm00189.md when improving the skill process or when investigating a similar read/write frequency screen.
Browser Capture Checklist
Capture enough runtime evidence to explain what the user sees and how the SQL changes:
- Login entry point, navigation path, final URL, screen title, and module.
- Search terms used in the menu/page search field and the selected result.
- Initial grid SQL, page size, default order, visible columns, hidden key fields, and default bind values.
- Company selector or scope selector values, including special values such as
-1 and -2 when present.
- Filter behavior for each visible search field, including empty/null/default behavior.
- Tabs and nested grids loaded only after user interaction.
- Links to related screens and the exact parameters passed in the URL or runtime state.
- Action buttons, edit/delete/detail flows, confirmation dialogs, and whether the screen appears read-only.
- Runtime/debug SQL snippets,
sqlSelect, sqlParameters, component ids, and observed bind values.
Prefer concise evidence snippets. Do not paste huge XML/debug dumps into the final report.
XML And SQL First
Before deep Oracle investigation, extract from the screen XML/debug:
- Component id and user-visible area.
sqlSelect and sqlParameters.
- Bind token order and default/null behavior.
- Lookup/combo SQLs.
- Linked screen URLs and parameter names.
ROWID, hidden ids, composite keys, generated columns, and any edit/delete a
…(truncated)
1---2name: ergon-archon-screen-discovery3description: Investigate legacy Ergon/Archon screens for Oracle lineage and Java API migration. Use for screen workflow, debug/XML components, SQL lineage, resources and Parte 1 API contracts. Requests to identify or migrate active customer customizations or business rules on a write operation belong to ergon-rule-migration-orchestration, even when a screen identifier is the only context.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/ergon-archon-screen-discovery6---78# Ergon Archon Screen Discovery910When available, consult the derived `praxis-screen-discovery-matrix` before11starting discovery to choose comparable pilots and identify known contracts or12runtime gaps. Regenerate it after discovery changes the operation inventory or13phase gate. It is an index only: XML/runtime evidence, the phase gate and the14canonical Praxis resource contract decide discovery conclusions.1516Use this skill to turn an exploratory Ergon/Archon screen investigation into a reproducible migration package. Prefer evidence-backed conclusions over naming conventions. When coordinating a multi-phase migration, use `ergon-migration-orchestration` first to verify phase gates and artifact handoff.1718## Rule-intent handoff1920Do not answer a Parte 2 request for an active customer customization from XML,21JavaScript, `onChanged`, field validation or another client-side screen rule22merely because those sources are easy to locate. A short prompt such as23“identifique uma customização cliente ativa na escrita de <SCREEN>” carries an24intent plus identifier: resolve the existing Parte 1 write handoff and route to25`ergon-rule-migration-orchestration`. You must use that skill before issuing26any active/inactive conclusion; do not finish the request inside screen27discovery. Screen discovery may contribute the28operation and DB-backed route, but it must not substitute a UI rule for the29requested customer-specific server-side rule.3031If both a client-side validation and an Oracle/HADES customer extension exist,32preserve both as distinct origins and let the rule workflow classify the33requested one. Do not ask the user to spell out HADES flags, owners, EP names,34packages or source ranges that the factory is expected to discover.3536For developer onboarding and day-to-day execution, use [developer-quickstart.md](references/developer-quickstart.md). For repeatable starts, use [prompt-template.md](references/prompt-template.md). For didactic PT-BR user guidance and ready-to-use prompts by reading/discovery scenario, use [read-prompt-examples.md](references/read-prompt-examples.md). For team handoff review, use [handoff-review-checklist.md](references/handoff-review-checklist.md). For database access provisioning, use [codex-oracle-access.md](references/codex-oracle-access.md). For authenticated browser-session capture, use [codex-browser-runtime-capture.md](references/codex-browser-runtime-capture.md) and [runtime-capture-form-template.md](references/runtime-capture-form-template.md). For Cronos XML source-of-truth decisions, use [cronos-source-of-truth-template.md](references/cronos-source-of-truth-template.md). For legacy documentation discovery, use [legacy-docs-discovery.md](references/legacy-docs-discovery.md). For component-to-API inventory, use [component-lineage-matrix-template.md](references/component-lineage-matrix-template.md). For read endpoint parity gates, use [read-parity-matrix-template.md](references/read-parity-matrix-template.md). For Java/API package-state parity, use [java-oracle-session-context.md](references/java-oracle-session-context.md). For API endpoint design, use [api-design-patterns.md](references/api-design-patterns.md), [lib-ui-fieldspec-api.md](references/lib-ui-fieldspec-api.md), and [java-api-implementation-playbook.md](references/java-api-implementation-playbook.md). For a filled read-first frequency API model, use [example-ergadm00189-api-contract.md](references/example-ergadm00189-api-contract.md). For architecture-level write patterns, use [archon-write-patterns.md](references/archon-write-patterns.md). For write behavior and write deferral, use [write-risk-template.md](references/write-risk-template.md), [write-risk-detail-template.sql](references/write-risk-detail-template.sql), and [write-api-handoff-template.md](references/write-api-handoff-template.md). For deciding whether a screen can move to API implementation, use [closure-checklist-template.md](references/closure-checklist-template.md).3738## Platform Governance3940Apply the root migration `AGENTS.md` while producing discovery artifacts. The41screen discovery phase must identify whether a finding belongs to the Ergon42host, `praxis-metadata-starter`, `praxis-config-starter`, `praxis-ui-angular`,43or another owner.4445When discovery finds missing or weak support for `_links`, `/actions`,46`/surfaces`, `/capabilities`, `/schemas/filtered`, `x-ui`, option sources, or47Angular runtime behavior, do not prescribe an Ergon-local workaround as the48default. First classify the need as `ja-suportado-so-ux`,49`ja-suportado-mal-nomeado-ou-mal-materializado`,50`suportado-parcialmente`, or `lacuna-real-de-contrato`. Only real contract51gaps should become `Praxis Platform Follow-up`.5253Keep HADES, SQL, `ROWID`, empresa, usuario, perfil, package names, and session54context as evidence for backend implementation, not public DTO/schema/URL/x-ui55contract.5657## Operating Principle5859Investigate in this order unless the user gives a stronger reason to change it:60611. Open the legacy screen and observe the actual user workflow.622. Find the Archon XML/debug definition for the same screen.633. Extract screen SQL, component names, bind tokens, links, filters, page size, hidden fields, and default values from browser/XML evidence.644. Use the extracted SQL objects as the seed list for Oracle metadata discovery.655. Expand Oracle lineage, security, grants, triggers, keys, and write risks only after the screen evidence is anchored.666. Close write behavior as either API-ready or explicitly blocked/deferred with evidence before claiming read/API readiness.6768Do not start from broad Oracle scans or name matching when browser/XML evidence is available. The screen XML and runtime SQL are the primary evidence for what the user-facing workflow actually uses.6970## Standard Operation Inventory7172Every Ergon/Archon screen discovery must produce or update `operation-inventory.md`. Start from the standard framework operations and then mark each one with one of the allowed states: `Implemented`, `Ready`, `Candidate`, `Blocked`, `Deferred`, or `Not present`.7374- `Consultar/listar`: default load, visible filters, pagination, sorting, company/user scope, empty state.75- `Ler detalhe`: row selection, detail form/panel, nested grids, public key, internal locators.76- `Novo/Salvar`: create button, edit state, defaults, required fields, validation messages, `P_OPER`/routine/table route, success side effects.77- `Editar/Salvar`: editable fields, immutable keys, changed-field payload, validation messages, side effects.78- `Apagar`: delete/anulation button, confirmation text, permission and dependency blockers.79- `Duplicar`: copied/defaulted values, new key fields, whether it reuses create route.80- `Cancelar`: no-op behavior from create/edit/duplicate modes.81- `Documentos legais`: tab/block/component, read source, write route when editable, `PONTLEI` or equivalent link key.82- `Publicacoes/atos`, `Pendencias`, and other related framework blocks when visible in XML, browser, or table-rule side effects.8384For each row, record: browser evidence, XML/component evidence, Oracle/source evidence, candidate endpoint, FieldSpec/platform mapping, current backend state, parity state, and exact next check. Do not collapse `Novo`, `Editar`, `Apagar`, `Duplicar`, and `Documentos legais` into a generic "writes pending" note.8586Use this FieldSpec mapping baseline when filling `operation-inventory.md`:8788- `Consultar/listar`: `POST /<resource>/filter` backed by `BaseResourceService.filterWithIncludeIds`.89- `Ler detalhe`: `GET /<resource>/{id}` backed by `BaseResourceService.findById`; `GET /by-ids` when the UI needs selected-row reloads.90- Lookups/options: `POST /options/filter`, `GET /options/by-ids`, `OptionDTO`, and `@UISchema(endpoint/filterField/sortField/optionsPageSize)`.91- `Novo/Salvar`: `POST /<resource>` backed by `save` only after write gates close; otherwise blocked/deferred.92- `Editar/Salvar`: `PUT /<resource>/{id}` backed by `update` only after update payload and side effects close.93- `Apagar`: `DELETE /<resource>/{id}` backed by `deleteById`; batch delete is a separate explicit decision.94- `Duplicar`: `POST /<resource>/{id}/duplicate-draft` through `DuplicateDraftResourceService.duplicateDraft`, then normal create on save.95- `Cancelar`: no backend mutation; prove UI state reset/no write.96- `Documentos legais`, `Publicacoes/atos`, and `Pendencias`: separate related resources/workflows unless runtime/XML proves they are fields of the main resource.9798For Ergon screens that depend on `HADES.FLAG_PACK`, note that the FieldSpec endpoint shape stays standard while implementation must run context setup/cleanup on the same Oracle connection through the shared legacy bridge.99100## New Platform Reuse Discovery101102After the legacy operation inventory is anchored, search the target Java/OMS modules before creating new API candidates. Produce `platform-reuse-inventory.md` with one row per operation/resource and a decision: `reuse`, `extend`, `create`, `block`, `defer`, or `not-api`.103104Inspect at minimum:105106- endpoint/path constants and OpenAPI groups;107- controllers, resource services, DTOs, FilterDTOs, mappers, repositories, entities, and tests;108- resources already migrated for related screens or shared lookups/options;109- `docs/migracao/platform-option-sources.md` generated by `tools/migration-factory/export-platform-option-sources.ps1 -Force` when the workspace has that helper, plus `docs/migracao/options-lov-promotion-status.md`, before treating a LOV/option as new or blocked; record `generatedAt`, covered property files/modules, and promotion status source so a missing source is not inferred from stale or incomplete coverage;110- shared services for legacy context, authorization, legal documents, publications, pending flows, and FieldSpec schemas;111- semantic gaps between the existing new-platform resource and the legacy screen behavior.112113If an existing resource matches the legacy operation, record the exact path/class and prefer reuse or extension. Do not propose a duplicate endpoint unless the incompatibility is explicit.114For LOV/options, record `PLATFORM_OPTION_SOURCE_RESOLVED` when sourceKey, dependencies, selected-value reload, and visible semantics match; `PLATFORM_OPTION_SOURCE_REVIEW_REQUIRED` when an existing source is close but semantically incomplete; and `PLATFORM_OPTION_SOURCE_BACKLOG_REQUIRED` only when no configured/promoted source fits and the target microservice/module was covered by the inventory. For dependent sources, selected-value reload must be proven separately from filtering: either the ID is self-contained for `GET .../by-ids`, or the contextual `POST .../by-ids` path is implemented and consumed with the required public dependencies. Treat review-required as an `extend` decision by default; use `block` only when the gap prevents the current screen contract.115116## Phase Boundary117118Use this as phases 1 and 1.5 of the migration:1191201. `ergon-archon-screen-discovery` discovers and closes the screen boundary: browser workflow, XML/runtime SQL, Oracle lineage, keys, scope, authorization, read API candidates, and write risk/handoff.1212. It may produce a candidate read API contract, but `ergon-archon-read-api-migration` owns final read API design/implementation.1223. Write endpoints remain `Blocked` or `Deferred` unless write behavior is fully closed.1234. When write remains blocked/deferred, create `write-risk.md` and `write-api-handoff.md` so `ergon-archon-write-api-migration` can run after the read API phase.1245. Before leaving phase 1, close the screen's write surface: visible actions, XML/runtime action source, candidate routines/tables, payload evidence or explicit gap, key/ROWID strategy, session context, and blockers.1256. Before handing off to `ergon-archon-read-api-migration`, create `read-parity-matrix.md` from [read-parity-matrix-template.md](references/read-parity-matrix-template.md). Do not mark the read phase as closed if list/detail/options/related read endpoints lack explicit parity status and gaps.1267. Before handing off to read/write API skills, produce `platform-reuse-inventory.md` or mark reuse discovery blocked with exact missing repository/module access.1278. Use `ergon-table-rule-audit` only for table-level write-rule closure, normally after the read API phase and after target tables are known.128129If the user asks for write implementation before these artifacts exist, keep the work in discovery mode and close the missing handoff evidence first.130131## Discovery Gates132133Before starting Phase 1, require an entry gate. `docs/migracao/<SCREEN>/migration-plan.md` and `phase-0-execution-gate.md` must exist, the target screen code must be explicit, and Fase 0 must recommend `ergon-archon-screen-discovery`. If these are missing, do not create a partial discovery package by hand; return to `ergon-migration-orchestration` and the canonical roadmap entry point.134135At the start of discovery, record the evidence plan: browser/runtime availability, runtime XML/local XML/HADES source plan, `docs-legado` paths to search, Oracle access status, expected factory helpers, and whether the intended slice is quick discovery, full discovery, or API migration. Missing browser, Oracle, XML export, or docs access is not fatal by itself, but it must become an explicit `Blocked`, `Partial`, or `Unavailable` status in the gate and artifacts.136137Before handing off to any API implementation skill, require an exit gate. The package must contain `phase-1-execution-gate.md`, `closure-checklist.md`, `component-lineage-matrix.md`, `operation-inventory.md`, `read-parity-matrix.md`, Oracle/HADES confirmation or blocked rerun artifacts, and a candidate `api-contract.md` when API migration is in scope. A gate may be `Ready for read API`, `Read handoff ready; write deferred`, `Ready for write API`, `Blocked`, or `Deferred`; it must not be implied by the presence of Markdown files alone.138139Legacy documentation under `docs-legado` is primary evidence for business meaning, historical model context, related flows, and parity scenarios, but it is not implementation proof by itself. Promote a doc fact into API readiness only after it is tied to browser/runtime, XML/debug, local source, Oracle metadata, or an explicit accepted deferral.140141## Legacy System Access142143Default demo entry point:144145- `http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm_mnu001.tp`146147Use the authenticated browser surface that actually has the session. Prefer the Codex in-app browser when the user has it open or can log in interactively. Use Chrome when the user asks for Chrome, the authenticated session is already in Chrome, or the user's profile/extensions are needed. Use Playwright only as a fallback for repeatable screenshots or scripted smoke checks after the browser-session path is understood.148149Legacy Archon pages can have unstable DOM locators. If DOM inspection hangs or returns unreliable results, use screenshots plus coordinate/CUA-style actions to operate the page, and record the limitation in `browser-runtime.md`. Do not downgrade confirmed visible behavior just because DOM automation is weak.150151If credentials are provided in the conversation, use them only for the active private session, but do not write them into reports, SQL files, commits, logs, screenshots, command history artifacts, or generated files. If credentials need to be reused locally, prefer environment variables or a private password manager outside the repository.152153After login:1541551. Confirm the authenticated Home/Menu screen: visible user, visible company, current URL path, and current menu transaction.1562. Click or focus the search field labeled like `Buscar transacao`.1573. Search for the target page code first, for example `ERGadm00033`, `ERGadm00034`, or `ERGadm00189`. Search by visible title only if the code does not return a result.1584. Open the matched page from the search result instead of guessing the final URL.1595. Record the selected result text, navigation path, visible title, module/breadcrumb, and final URL path.1606. Exercise the visible workflow: default load, company selector, search/filter fields, tabs, links, action buttons, pagination, and detail navigation.1617. Capture observed parameters and changed SQL behavior after each interaction.162163If the search does not find the transaction, try the visible menu/area path and record each clicked label. If neither search nor menu opens the screen, mark navigation as `Blocked - screen not reachable for current user`.164165If login or browser access is unavailable, continue from local XML/source and mark `Observed` as `Missing` or `Partial` in the gates.166167## Runtime XML Export Gate168169For Cronos/Archon `.tp` transactions, always try the matching `.xml` runtime export before treating local XML as final:170171```text172/<Application>/<Module>/<Transaction>.xml173```174175Example: `http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm00034.xml`.176177This route is handled by Cronos export code, requires an authenticated user with layout-export permission (`privilegiado` or `alteraLayout`), retrieves the runtime descriptor, and serializes it through `TransactionXmlWriter`. It is not merely a static file read.178179If `tools/migration-factory/download-runtime-xml.ps1` exists in the repository, run it before any manual extraction from the browser viewer. It is the preferred path because it saves the raw response only after XML parser validation and writes sanitized evidence. Pass credentials only through a pre-created `PSCredential` or pre-existing env vars; do not put secrets in the command.180181Required behavior:1821831. Use credentials only for the active private session; never write them to artifacts, logs, SQL, commits, screenshots, command history, or prompt templates.1842. Open the `.tp` route to prove the runtime screen is reachable for the current user.1853. Download the `.xml` route for the same application/module/transaction. If browser JavaScript cannot read `HttpOnly` cookies or lacks `fetch`/`XMLHttpRequest`, do not stop there: when the login page exposes a form, parse the actual `<form action>` and resolve it against the response URL. Example: `action="/login"` under `/Ergon/Administracao/<SCREEN>.tp` resolves to `http://host/login`, not `/Ergon/login`. Use an in-memory HTTP session/cookie container to request `.tp`, submit the resolved login action with the observed form fields, then request `.xml`. Keep credentials and cookies only in memory.1864. Save the exported XML under `docs/migracao/<SCREEN>/runtime/<SCREEN>.authenticated.xml` or `docs/migracao/<SCREEN>/runtime-exported-xml/<SCREEN>.xml` only when it contains no credentials or sensitive runtime data beyond screen metadata and the saved file parses as XML.1875. Record URL, HTTP status, redirect/login status, content type, byte size, SHA-256 hash, parser result, timestamp, and non-sensitive user/session context.1886. Compare exported XML against local product XML under `docs-legado/**/crodata/trans/<Module>/<Transaction>.xml`.1897. Produce or update `cronos-source-of-truth.md` with one of: `RUNTIME_EXPORTED_XML_MATCH`, `RUNTIME_EXPORTED_XML_DIVERGED_FROM_LOCAL`, `RUNTIME_XML_EXPORT_FORBIDDEN`, `RUNTIME_XML_EXPORT_AUTH_BLOCKED`, `RUNTIME_XML_EXPORT_NOT_FOUND`, or `LOCAL_XML_ONLY_UNCONFIRMED`. This artifact is mandatory whenever a runtime XML, local XML, HADES/stored XML, or XML-export residual exists. If HADES/Oracle is unavailable, still create the file and mark the source-of-truth decision `Blocked` or `Partial`; do not leave the decision only inside `investigation.md`.190191Never use `document.documentElement.outerHTML` from Chromium's XML viewer as the raw XML export; it can capture the viewer page instead of the original resource. If the raw XML cannot be saved, record the exact attempted methods and residual such as `XML_RAW_EXPORT_NOT_SAVED`.192193Do not treat copied/rendered text from Chromium's XML viewer as raw XML unless an XML parser accepts the saved file. The viewer can display escaped XML attribute content as literal markup, producing invalid XML such as attributes containing raw `<div ...>`. If parsing fails, classify the file as `RUNTIME_XML_BROWSER_TEXT_INVALID`; use it only as diagnostic evidence and continue from parser-valid local XML, raw HTTP export, or HADES/Cronos source.194195Never place credential literals in shell commands, generated scripts, report snippets, or command transcripts. Prefer a local secrets/env file, environment variables, or an already-authenticated browser session. If no safe non-recording credential path exists, ask the user for one before running an HTTP login from the shell.196197When credentials exist only in the active conversation/session, prefer logging in through the authenticated browser surface over embedding credentials in shell. If browser automation cannot safely submit the login, ask the user to log in manually and continue from that session. Even without submitting credentials, parse and record sanitized login mechanics from the login HTML: resolved form action, method, field names, HTTP status, and issued cookie names only.198199Use exported runtime XML as the primary structural source when it exists and diverges from local XML. Still capture browser/runtime evidence for SQL behavior, binds, permissions, action availability, write payloads, and dynamic controller behavior; exported XML alone does not close API parity.200201## Cronos Bind And Scope Resolution202203For Cronos/Archon screens, do not treat Chrome/browser automation as the only204way to close bind semantics. When the open question is bind order, lookup source,205special selector values, or company/session scope, first combine parser-valid XML206and Oracle metadata:2072081. Read `sqlParameters` and bind order from the runtime XML or from the accepted209 source in `cronos-source-of-truth.md`.2102. Read the SQL predicate where the bind is applied, for example `VALOR = ?`.2113. Locate the reused component definition or an equivalent screen component that212 defines the same control.2134. Resolve the combo/searchbox source through Oracle metadata, view text,214 dependencies, synonyms, or package/function source.2155. Save the read-only Oracle output under `docs/migracao/<SCREEN>/oracle-results/`.2166. Classify the bind as public filter, server-side scope, constant bind,217 parent-row context, or internal runtime parameter.218219Example pattern already proven in `ERGadm00034`: `component/HADadm_blk003`220exposes `drpSelecEmpresa`; equivalent screens define it with221`select valor, descr from SELEC_COMBO_EMPRESA_VW order by valor`; Oracle view222text confirms `-1` = all companies, `-2` = no company, and223`flag_pack.get_empresa` = current company. That means `VALOR` is internal224company/query-mode scope, not a public `FilterDTO`, schema, URL, `OptionDTO.extra`,225or x-ui field when a functional key exists.226227### Public Identity Must Follow The Effective Legacy Query228229Never infer a composite or opaque public id merely because a legacy view230contains duplicate domain keys. First distinguish view fan-out from entity231identity:2322331. prove the base-table PK/UK and its projection through the view;2342. reconstruct the exact list/detail query used by the component;2353. apply server-side scope/session binds under the same Oracle connection;2364. test key uniqueness in that effective resource slice;2375. confirm how child components and legacy operations identify the selected row.238239The unscoped view count is diagnostic only. If the domain key is unique in the240effective slice, expose that key and keep company, user, HADES state, `VALOR`,241`ROWID`, and equivalent locators internal. If duplicates remain, determine242whether they are projections of the same entity or genuinely distinct public243resources before considering normalization, a composite key, or an opaque id.244Record `candidate_public_key_unique_in_effective_scope` when the effective probe245proves one selected-row match and key uniqueness. Record246`blocked_effective_scope_key_uniqueness_not_proven` when that probe has not run247or its same-connection scope is not reproducible; do not convert uncertainty248into an opaque-token design.249250Use `docs/migracao/phase1-cronos-bind-resolution-standard.md` when present. If251XML plus Oracle metadata closes the semantics and no browser evidence252contradicts it, record `BIND_SEMANTICS_CLOSED_BY_XML_ORACLE` or equivalent in253the gate instead of blocking only because Chrome/browser automation is254unavailable. Browser/runtime evidence is still required for visible workflow,255action availability, messages, write payloads, restricted-user behavior, and256final legacy/API parity.257258## Cronos RecordPanel Write Payload Resolution259260For standard Cronos/Archon write panels, do not make browser navigation the first261or only path to close create/update payloads. If XML shows262`component/recordPanelEdit` with `dataTable` and without `rotina`,263`insertMethod`, `updateMethod`, or `deleteMethod`, resolve the payload from264parser-valid XML plus the local Cronos framework source before asking the265developer to operate the browser.266267Required source-derived check:2682691. Locate the `recordPanelEdit` component and its `dataTable`.2702. Extract sibling/child `component/editField/*` controls in layout order:271 `field`, `fieldTarget`, `caption`, `dataType`, `required`, `validators`,272 `initialValue`, `valueProperty`, `displayProperty`, and lookup SQL/options.2733. Confirm in Cronos source that `RecordPanelEditImpl` dispatches `dataTable` to274 `createManagerDescription()`.2754. Confirm `ManagerDescriptionParameters` uses `_op` for operation, `_p_` for276 proposed values, `_o_` for original values, and `_q_p_` for query/reload277 values.2785. Confirm `ManagerTableParametersImpl` and `AbstractTableDescription` generate279 table `INSERT`, `UPDATE ... WHERE PK`, and `DELETE ... WHERE PK`.2806. Confirm `ManagerDescriptionImpl` executes the generated Oracle SQL on the281 application connection and reloads rows by internal rowid/query description.282283When `tools/migration-factory/new-cronos-recordpanel-write-payload.ps1` exists,284run it with `-Strict` and save the generated Markdown/JSON under285`docs/migracao/<SCREEN>/factory/`. A passing result may close create/update286payload discovery as `SOURCE_DERIVED_PAYLOAD_READY_FOR_DB_PROBE`.287288This source-derived payload replaces browser payload capture for the standard289`recordPanelEdit + dataTable` pattern. Browser remains useful for visible290success/error messages, action availability, duplicate defaults, permissions,291cancel/no-op behavior, and final UI parity, but it should not block payload292closure when XML + Cronos source already prove the route.293294## Assisted Codex Browser Session295296When the in-app browser is available, ask the developer to log in once if needed, then operate from the authenticated page. For direct URLs such as:297298```text299http://ergon-demo-644.techne.com.br/Ergon/Administracao/ERGadm00189.tp300```301302record the page as `Browser access status: Partial` as soon as the authenticated screen is visible, even before every workflow is exercised. Then complete the observation by clicking through the visible UI:303304- Confirm final URL, title, module, and whether the menu/search path also finds the page.305- Inspect frames, popups, debug panels, XML/debug buttons, network/runtime SQL panels, and hidden fields exposed by the legacy UI.306- Prefer direct browser observation for dynamic behavior that automation often misses: enabled/disabled actions, popup navigation, row selection, tab lazy loading, validation messages, and session-specific authorization.307- Save only concise evidence. Do not dump full page HTML, screenshots with sensitive data, or credential-bearing logs into the migration package.308- If Codex cannot programmatically inspect the in-app browser in the current environment, have the developer keep the page open and use browser-visible facts they provide as `CONFIRMED_RUNTIME_MANUAL`; do not upgrade SQL/bind behavior to `CONFIRMED_RUNTIME` until Codex or a captured debug artifact verifies it.309310Create or update `docs/migracao/<SCREEN>/browser-runtime.md` using [codex-browser-runtime-capture.md](references/codex-browser-runtime-capture.md). Also create `runtime-capture-form.md` from [runtime-capture-form-template.md](references/runtime-capture-form-template.md) when Codex cannot inspect the browser DOM directly and the developer must relay visible/debug facts. `browser-runtime.md` is the working runtime notebook; summarize only stable findings back into `investigation.md`.311312For Phase 1 validation before developer handoff, `runtime-capture-form.md` is not a substitute for executed runtime evidence. If default load, runtime bind values, page size, selected-row/public-key proof, visible action state, or representative non-empty fixture/context are missing, close Phase 1 as `Blocked`; do not mark it `Ready for next phase` or `Ready for next phase with adjustments`.313314When the workspace provides `docs/migracao/phase1-scope-authorization-standard.md`, use it as the Phase 1 scope/authorization contract. The factory workbook should record `phase1-scope-authorization-v2-bridge` when the screen is an API-only Ergon/HADES bridge. `allowed-default-context` can close only with authenticated browser default load, non-empty fixture, selected row, public-key correlation, and same-connection Ergon/HADES Oracle context. For API-only screens governed by `ergon-hades-security-starter` and `ergon-legacy-bridge`, `company-scoped-context` and `restricted-user-context` close by the shared bridge/security contract and must not block each screen individually. Reopen them as blocking only when the screen bypasses `HadesLegacyAccessGuard`/equivalent, bypasses `ErgonLegacyExecutor`/equivalent, exposes company/user/profile/security context publicly, or implements custom security outside HADES. When the factory provides `new-phase1-scope-authorization-decision-pack.ps1`, generate its Markdown/JSON pack only for genuinely open scope cases; the pack requests owner decisions but does not close Phase 1 by itself. Do not turn company, user, profile, permission, or session binds into public FilterDTO/schema/URL/option/x-ui fields.315316## Workflow3173181. Identify the target screen code, URL, title, module, and user-visible workflow.3192. Open the default legacy entry point when no direct URL is known, log in using credentials provided by the user for the active session, and locate the screen through the page/menu search field.3203. Run the Runtime XML Export Gate for the matching `.xml` route. If export succeeds, compare it with local product XML and use the runtime export as the primary structural source when it diverges. If export is blocked, record the blocker and continue with lower confidence.3214. Inspect the running screen with the Codex in-app browser when available, or Chrome when the user's Chrome profile is required. Capture visible grids, tabs, actions, links to related screens, debug tree nodes, XML/debug `sqlSelect`, `sqlParameters`, page size, filters, hidden fields, and observed bind values. If browser inspection is unavailable, continue from local XML/source and mark browser evidence as missing or manual-only.3225. Inspect local legacy artifacts when present, especially `docs-legado/**/<SCREEN>.xml`, view scripts, Java services, DTOs, and resource classes. Treat XML `sqlSelect`, `sqlParameters`, component ids, links, and filter bindings as an initial source for Oracle seed objects only after classifying runtime export availability.3236. Inspect the legacy architecture/documentation tree when `docs-legado/v7x` is available using [legacy-docs-discovery.md](references/legacy-docs-discovery.md). This tree has known evidence layers: Archon XML/controllers under `java`, local DDL/source under `aps`, Enterprise Architect exports under `EA`, RoboHelp model/reference archives under `help`, functional/technical specs under `docs/Interno`, workflow assets under `workflow`, and older Forms/Reports assets under `forms` and `reports`. Use these sources for business meaning, candidate parity cases, model context, and related-flow discovery; do not let documentation override browser/XML/Oracle evidence.3247. Build a narrow seed list from browser/XML SQL before querying Oracle. Include screen views, lookup views, linked-screen views, packages/functions referenced by SQL, and objects introduced by related flows.3258. Query Oracle metadata using [oracle-queries.md](references/oracle-queries.md). Treat `ERGON` and `HADES` as defaults, not universal owners. Resolve synonyms, expand views recursively, inspect columns, constraints, indexes, triggers, grants, package arguments, source references, updatable columns, and write risks.3269. Classify every object by role and confidence. Do not promote structural matches to confirmed objects without evidence.32710. If screen SQL, views, helpers, triggers, or packages depend on Oracle package state such as `HADES.FLAG_PACK`, document the Java same-connection context strategy using [java-oracle-session-context.md](references/java-oracle-session-context.md). Do this before marking any Java/API contract as ready.32811. Produce or update read-only Oracle confirmation SQL from [oracle-confirmation-template.md](references/oracle-confirmation-template.md) when Oracle access is available or when follow-up confirmation is needed. When the repository has `tools/migration-factory/new-phase1-oracle-sql.ps1` and `factory/extraction.json` exists, use that generator before writing any manual Oracle/HADES SQL. It standardizes `oracle-confirmation.sql` and `hades-registry.sql` from XML seeds, preserves owner/package/subprogram identity, avoids known dictionary mistakes such as `ALL_PROCEDURES.STATUS`, expands view/physical lineage, reports owner collisions, covers HADES registry/access/menu/stored-resource candidates, and adds minimal non-empty smoke probes for read/view seeds. Manual SQL is allowed only as a supplemental artifact with the exact reason recorded in the gate. A Phase 1 package must include both object confirmation coverage and HADES registry coverage, either in `oracle-confirmation.sql` plus `hades-registry.sql`, or in one clearly sectioned SQL file. Use the executed outputs to fill the component-to-API matrix and candidate API contract facts: DTO fields, FilterDTOs, options, keys, scope, authorization, session context, related resources, and blocked/deferred writes. If execution fails, save a sanitized blocked note under `oracle-results/` and keep all Oracle/HADES findings below `CONFIRMED_ORACLE_METADATA`. Before closing the gate, scan every referenced Oracle/tool output for `ORA-`, `SP2-`, `TNS-`, `ERROR:`, `Exception`, and `IllegalArgumentException`; a corrected supplemental SQL may supersede a failed statement only when the gate explicitly records the failed output and the replacement evidence.32912. Create or update `read-parity-matrix.md` from [read-parity-matrix-template.md](references/read-parity-matrix-template.md). For every read endpoint candidate, record the legacy component, Oracle source, Java/API source if it exists, key strategy, filters/binds, paging/sort, options behavior, HTTP/API execution status, and the exact remaining gap. A read API can be "implemented" and still not be "parity closed".33013. When the XML/browser shows create, edit, delete, duplicate, pending, publication, legal-document behavior, or `recordPanelEdit` with a `db:*` routine, read [archon-write-patterns.md](references/archon-write-patterns.md), then create `write-risk.md` from [write-risk-template.md](references/write-risk-template.md) and a focused `write-risk-detail.sql` from [write-risk-detail-template.sql](references/write-risk-detail-template.sql). Use exact routines/tables/triggers from XML/runtime evidence; avoid broad table-name source searches. If the screen is closed as `Ready for read API` or receives a read-first implementation while write remains blocked/deferred, create `write-api-handoff.md` from [write-api-handoff-template.md](references/write-api-handoff-template.md).33114. Before starting Phase 3 write design, close write payloads for every visible write action in scope. For standard Cronos `recordPanelEdit + dataTable`, prefer the source-derived XML + Cronos framework path above and then require a controlled DB probe. For rotina/object-method/custom actions, or when XML/source does not prove the route, capture runtime write payloads for `Novo`, `Editar`, `Apagar`, `Duplicar`, `Salvar`, `Cancelar`, legal-document actions, publication actions, pending actions, and any screen-specific business action. Record UI state before/after click, confirmation dialogs, hidden keys such as `ROWID_REG`, operation selector values, selected public id, `P_MENS`, routine arguments, legal-document/publication/pending fields, changed debug/network request, and observed validation messages. If neither source-derived payload nor runtime payload can be captured, mark the operation `Blocked` or `Deferred` with the exact next XML/source/browser/debug step; do not leave `operation-inventory.md` with a generic `Unknown` backend state and do not infer payloads from PL/SQL signatures alone.33215. Use gates before finalizing: `Observed`, `Resolved`, `Expanded`, `Read-parity planned/executed`, `Write-risk checked`, `False-positive checked`, `Confirmation SQL complete`, `Session-context checked`, and, for Java work, `API-ready`.33316. Produce the investigation report using [investigation-template.md](references/investigation-template.md).33417. If the user is planning Java migration, read [api-design-patterns.md](references/api-design-patterns.md), [lib-ui-fieldspec-api.md](references/lib-ui-fieldspec-api.md), and [java-api-implementation-playbook.md](references/java-api-implementation-playbook.md), then produce the API contract using [api-migration-template.md](references/api-migration-template.md). Keep endpoints as `Candidate`, `Blocked`, or `Deferred` until keys, scope, authorization, session context, runtime binds, FieldSpec contract, read parity plan, and write boundaries are closed.33518. Load [example-ergadm00033-findings.md](references/example-ergadm00033-findings.md) only when the target is ERGadm00033/ERGadm00034 or when the user explicitly asks for that example.33619. Load [example-ergadm00189-findings.md](references/example-ergadm00189-findings.md) only when the target is ERGadm00189 or when the user explicitly asks for that example. Load [example-ergadm00189-api-contract.md](references/example-ergadm00189-api-contract.md) when drafting or validating a read-first frequency API contract.33720. Load [case-review-ergadm00189.md](references/case-review-ergadm00189.md) when improving the skill process or when investigating a similar read/write frequency screen.338339## Browser Capture Checklist340341Capture enough runtime evidence to explain what the user sees and how the SQL changes:342343- Login entry point, navigation path, final URL, screen title, and module.344- Search terms used in the menu/page search field and the selected result.345- Initial grid SQL, page size, default order, visible columns, hidden key fields, and default bind values.346- Company selector or scope selector values, including special values such as `-1` and `-2` when present.347- Filter behavior for each visible search field, including empty/null/default behavior.348- Tabs and nested grids loaded only after user interaction.349- Links to related screens and the exact parameters passed in the URL or runtime state.350- Action buttons, edit/delete/detail flows, confirmation dialogs, and whether the screen appears read-only.351- Runtime/debug SQL snippets, `sqlSelect`, `sqlParameters`, component ids, and observed bind values.352353Prefer concise evidence snippets. Do not paste huge XML/debug dumps into the final report.354355## XML And SQL First356357Before deep Oracle investigation, extract from the screen XML/debug:358359- Component id and user-visible area.360- `sqlSelect` and `sqlParameters`.361- Bind token order and default/null behavior.362- Lookup/combo SQLs.363- Linked screen URLs and parameter names.364- `ROWID`, hidden ids, composite keys, generated columns, and any edit/delete a365366…(truncated)