Ergon Migration Orchestration
Derived Discovery Matrix
Before prioritizing a screen, selecting a reusable pilot, or resuming a screen
whose gate predates the current migration cut, run
tools/migration-factory/export-praxis-screen-discovery-matrix.ps1 when it is
available and inspect the record for that screen. Use it only as a derived
operational index for resource candidates, gates, read/write state, Angular
runtime shape and next-action candidates. The phase gate, versioned contracts,
Praxis annotations and live canonical surfaces remain the sources of truth.
After a material phase closure, regenerate the matrix before changing portfolio
priority or promoting a screen as reference. Do not infer primary intent from
matrix labels or text; resolve the canonical resource, operation, action or
surface in its owner artifact first.
Use this skill as the top-level conductor for Ergon/Archon migrations. It does not replace the specialized skills; it decides the order, required artifacts, phase gates, and next action. When a phase enters a domain owned by another skill, route to that skill and preserve its gates instead of restating or weakening them here.
Core Rule
Never let a later phase compensate for missing evidence from an earlier phase silently. If an artifact is missing, either produce it now with the right skill or mark the phase as blocked with the exact gap.
Before changing code, contracts, templates, or migration artifacts, apply the
root migration AGENTS.md platform governance. Classify the change as
docs-apenas, local-pequena, transversal, contrato-publico, or
arquitetural; identify the canonical owner; and record the impact map when
the change touches public contract, multiple consumers, or architecture.
Before editing Java, Angular, module-owned docs/tests, or running a generator
against a target module, run the duplicate-module-root guard when a module
name/artifactId is known. Do not use this guard as a Phase 0 prerequisite for
creating workspace-owned screen artifacts under docs/migracao/<SCREEN>; run
it before the first module-owned edit instead:
python3 codex-skills/ergon-migration-orchestration/scripts/check_duplicate_module_roots.py \
--workspace-root <canonical-migracao-root-from-AGENTS> \
--module <module-directory-or-artifactId> \
--current-root <intended-edit-root>
If the current root is the canonical module under the canonical workspace,
duplicates outside that workspace (for example historical clones or issue
worktrees such as m79/<module>) are advisory: continue in the canonical root
without asking for human confirmation. The guard must still block when the
current root is noncanonical, when another matching root exists inside the
canonical workspace, or when the canonical root is outside a git checkout. If
it returns MIGRATION_MODULE_ROOT_GUARD_BLOCKED, stop before the module-owned
edit and use the canonical root from AGENTS.md or require an explicit human
choice. Its message must remain sanitized: no credentials, users, company
identifiers, headers, cookies, or environment secret values.
Skill Lock Drift Triage
When the migration workspace lock audit reports only a source commit mismatch,
do not spend the intake turn re-reading every installed copy or block creation
of the Phase 0 screen package automatically. Audit the selected canonical skill
family and its installed projection first:
- if source hashes match the family manifest and the selected installed skill
matches the canonical tree, record
CODEX_SKILLS_LOCK_DRIFT as a non-blocking
tooling residual and continue workspace-owned Phase 0 work;
- if the selected source is invalid or its installed projection differs, repair
the canonical manifest/sync before relying on the skill, and keep
module-owned edits blocked until that reconciliation passes;
- never update a workspace lock to represent uncommitted source changes. Refresh
the pin only after the canonical skill changes are committed.
A commit-only lock mismatch is still relevant before versioning or handoff, but
it must not cause a new-screen intake to end without its Phase 0 artifacts when
the selected skill tree itself is proven current.
Do not solve Praxis platform gaps by inventing Ergon-local semantics. If the
issue belongs to praxis-ui-angular, praxis-metadata-starter, or
praxis-config-starter, create a Praxis Platform Follow-up with objective
evidence and a prompt for the Praxis specialist. A temporary Ergon workaround
must have an owner, removal trigger, canonical replacement, and must prevent
the screen from being treated as a scalable example while it exists.
Every phase closeout must produce a reusable gate packet: final decision, evidence actually executed, residual issues with owners, explicit return-to-previous-phase rules, and the next recommended prompt/skill. If the screen advances with non-blocking residuals, classify it as Ready for next phase with adjustments and carry those residuals into the next phase and handoff.
Endpoint readiness is not a static-test decision. Do not call an endpoint Verified or promote it to handoff solely because unit tests, OpenAPI generation, schema assertions, or mocked service tests passed. For backend API handoff, require executed endpoint evidence plus legacy/API/database comparison with the same user/company/context and filters. If any part was not executed, use a narrower state such as Implemented with automated tests, Schema/static contract passed, Executed endpoint smoke, Legacy parity pending, Blocked, or Deferred.
For write operations, classify the route per operation instead of assuming either generic CRUD or DB-backed by default. The conservative default is: unknown rule, context, route, side effect, or error behavior means WRITE_DB_BACKED_REQUIRED or WRITE_BLOCKED. Direct table/Praxis CRUD can be approved only as WRITE_TABLE_DIRECT_SAFE when Phase 4/5 evidence proves it preserves required behavior, errors, session context, side effects, and parity.
Development Migration Mutation Authority
When the migration workspace provides
docs/migracao/development-mutation-authority.md, treat its declared
development database as persistently pre-approved for data mutation required by
migration. Do not ask for a new human confirmation per screen, API call,
marker, fixture, existing development row, cleanup, or retry. Execute the
technical preflight, use a disposable fixture where practical, restore the
baseline when an existing row is required, and record sanitized evidence.
This authority is not a shortcut around the write gates. WRITE_DB_BACKED_REQUIRED,
WRITE_TABLE_DIRECT_SAFE, WRITE_BLOCKED, and WRITE_DEFERRED still decide
which API route can be implemented or handed off. They must never be confused
with permission to run the controlled probe that produces the missing evidence.
Only an environment mismatch, unavailable connection/credential, unknown route,
or legacy/HADES rejection is a mutation blocker; record that technical fact
instead of asking whether mutation is allowed.
Track Boundaries
This skill coordinates tracks; it does not make local substitutes for canonical Praxis skills or runtimes.
- Backend/API Parte 1: Phases 0-8 cover legacy evidence, platform reuse inventory, read/options API, write audit/contract/implementation, parity, and backend handoff. Use
ergon-archon-screen-discovery, ergon-archon-read-api-migration, ergon-table-rule-audit, ergon-archon-write-api-migration, praxis-dto-annotations, praxis-java-host-project, and praxis-resource-entity-lookup-backend as required by the phase.
- Angular/UI Native Praxis track: Starts only from a closed backend handoff, scoped pilot handoff, or explicit backend gap package. Use
ergon-angular-ui-screen-wiring and the general Praxis UI skills it requires. UI work must consume canonical schemas, capabilities, HATEOAS links, actions, surfaces, option sources, and @praxisui/* runtime behavior; it must not introduce an Ergon-local action/surface/lookup/form/table runtime.
- Dashboard/analytics track: When the target is dashboard, KPI, cockpit, analytics, charts, stats, or aggregate metrics, route to
ergon-dashboard-praxis-charts plus praxis-dashboard-analytics. Do not model metrics as ordinary screen fields when the canonical analytics contract is required.
- Rule migration Parte 2: Starts only after the relevant Parte 1 baseline is closed and the rule scope has table-rule evidence, read/write boundaries, and parity residuals explicit. Use
ergon-rule-migration-orchestration; if it finds missing API, write, HADES, shadow-mode, or parity evidence, return to the exact Parte 1 phase that owns the gap.
Every cross-track handoff must state the selected skill, required inputs, expected outputs, residuals carried forward, and the return-to-previous-track rule.
Canonical Phase Management Artifacts
Use these files to make phase state deterministic across agents and developers:
docs/migracao/<SCREEN>/phase-<PHASE-ID>-execution-gate.md: required whenever a phase is classified as Ready for next phase, Ready for next phase with adjustments, Blocked, or Deferred. This file is the phase closeout; do not treat a functional artifact such as quality-round-2.md as a substitute.
docs/migracao/<SCREEN>/phase-<PHASE-ID>-<slug>-plan.md: optional planning/reentry artifact. Use it before execution when scope is partial, a previous gate carried residuals, fixtures are conditional, browser/API/Oracle evidence must be coordinated, mutation risk exists, or a phase is resumed after an earlier closeout. A plan is not execution evidence and is not a gate closeout.
<PHASE-ID> uses dots converted to hyphens: Phase 1.5 is 1-5.
When the user explicitly asks for planning only, create or update a phase-<PHASE-ID>-<slug>-plan.md and leave the phase state Open. When evidence has been executed or a phase decision is made, create or update the standalone phase-<PHASE-ID>-execution-gate.md.
Short Continuation Commands
If the latest phase gate is Ready for next phase or Ready for next phase with adjustments, a short user command such as continuar, seguir, ok, 1, or proximo is enough to start the next recommended phase.
When handling a short continuation command:
- Locate the latest
docs/migracao/<SCREEN>/phase-<PHASE-ID>-execution-gate.md.
- Confirm its state is
Ready for next phase or Ready for next phase with adjustments.
- Read the gate's
Continuacao Curta or next-step section as the source of truth.
- Start the recommended next phase with the recommended skill and required input artifacts; do not stop after merely restating the prompt when the gate is unambiguous.
- Carry residuals from the gate into the new phase.
- Do not ask the user for a long prompt unless the gate is missing, ambiguous,
Blocked, Deferred, or points to multiple possible next phases.
Short continuation is not automatic chaining. The user still needs to send a follow-up command, but it may be short because the gate is the source of truth.
Every phase gate that closes as Ready for next phase or Ready for next phase with adjustments must include a complete short-continuation contract: next phase, skill, required inputs, expected outputs, carried residuals, and the exact execution intent. If any of those fields is missing, treat the next short command as a request to repair/clarify the gate before running the next phase.
Standard Legacy Operation Inventory
Treat Ergon/Archon screens as framework-driven until evidence proves otherwise. At intake and discovery time, create an operation inventory for the screen using this baseline:
Consultar/listar: default grid/list load, filters, pagination, sorting, empty result, company/user scope.
Ler detalhe: row selection, detail panel, nested detail form, public key, internal ROWID/locator strategy.
Novo/Salvar: create mode, defaults, required fields, validation messages, generated DML routine/table route, success side effects, cleanup.
Editar/Salvar: update mode, immutable keys, changed-field payload, validation messages, side effects.
Apagar: delete/anulation button, confirmation dialog, permission/dependency blockers, cleanup and row preservation proof.
Duplicar: copied/defaulted fields, new-key strategy, save route, duplicate validation.
Cancelar: no-mutation behavior from create/edit/duplicate modes.
Documentos legais: legal-document tab/block, linked component/screen, PONTLEI/document locators, read/write scope.
Publicacoes/atos and Pendencias: include when visible, linked, or reached by triggers/packages, even if deferred from the current slice.
For every operation, record one of: Implemented, Ready, Blocked, Deferred, or Not present. Do not expose or hand off an operation unless its backend/API state is Implemented with parity evidence or intentionally blocked/deferred.
Standard Praxis Metadata/API Mapping
For every operation in the inventory, map the legacy behavior to the new platform surface before implementation:
| Legacy operation |
New platform/Praxis surface |
Required migration decision |
Consultar/listar |
POST /<resource>/filter; BaseResourceService.filterWithIncludeIds; DTO/FilterDTO metadata |
Implement filters, paging, sort, scope, authorization, empty state, and parity cases. |
Ler detalhe |
GET /<resource>/{id}; BaseResourceService.findById; optionally GET /by-ids / findAllById |
Choose stable public ID; keep ROWID internal unless explicitly accepted. |
| Lookups/options |
POST /<resource>/options/filter; GET /options/by-ids; OptionDTO; @UISchema(endpoint, filterField, sortField, optionsPageSize) |
Implement combo semantics and selected-value reloads used by the UI. |
Novo/Salvar |
POST /<resource>; BaseResourceService.save |
Use direct platform save only when safe; otherwise route through a screen-specific legacy-backed service under the shared Ergon bridge. |
Editar/Salvar |
PUT /<resource>/{id}; BaseResourceService.update |
Use command DTOs when read DTOs contain derived/internal fields; preserve legacy validation and side effects. |
Apagar |
DELETE /<resource>/{id}; BaseResourceService.deleteById; batch delete only when explicitly closed |
Prove confirmation, permission, dependency blockers, no-mutation failures, and cleanup. |
Duplicar |
POST /<resource>/{id}/duplicate-draft; DuplicateDraftResourceService.duplicateDraft; DuplicateDraftUtils; @UISchema(copyOnDuplicate) |
Generate an editable draft, then persist through POST; do not assume every copied field is allowed. Use @WorkflowAction only if runtime proves duplicate is a business command with its own immediate effect or dedicated workflow route. |
Cancelar |
No backend mutation |
Record no-op proof and avoid adding a backend mutation endpoint. |
Documentos legais |
Separate related resource or linked component API using the same filter/detail/write pattern |
Resolve link keys such as PONTLEI server-side and scope write only after parity is closed. |
Publicacoes/atos / Pendencias |
Separate related resource/workflow API; often backed by reusable legacy blocks or related transactions |
Do not fold into the main resource unless XML/runtime evidence proves the same route. |
All resources must also expose or deliberately block the relevant schema and action metadata: /schemas, /schemas/filtered, @UISchema, HATEOAS/action links, and explicit 405/501 or omitted routes for unsupported operations. For legacy-backed reads/writes that depend on Oracle package state, keep the Praxis metadata/API controller/service contract while placing same-connection HADES.FLAG_PACK setup, cleanup, procedure calls, and Oracle error translation behind the shared Ergon bridge.
Praxis semantic contract rules for Ergon:
- Treat the resource endpoint, DTO, FilterDTO, schemas, options,
_links, /actions, /surfaces, and /capabilities as one contract. Do not create parallel capability/action models for Ergon screens.
- Before creating a new endpoint, launcher, adapter, metadata field, action, surface, capability, option source, or Angular component, inventory the native Praxis support and classify the need as
ja-suportado-so-ux, ja-suportado-mal-nomeado-ou-mal-materializado, suportado-parcialmente, or lacuna-real-de-contrato. Only lacuna-real-de-contrato justifies a new Praxis contract request.
- Use the canonical owner map:
praxis-metadata-starter owns x-ui, schemas, HATEOAS, actions, surfaces, capabilities, annotations, and resource-oriented metadata; praxis-config-starter owns /api/praxis/config/**, user config, AI registry, templates, ETag, and AI authoring contracts; praxis-ui-angular owns the official Angular runtime, components, adapters, launchers, materializers, editors, and dynamic fields; praxis-api-quickstart is an operational reference, not the semantic owner.
- Keep simple create/update/delete as resource operations when the write gate proves they are safe. Do not mark
POST, PUT, or DELETE as @WorkflowAction only because the legacy UI had a button.
- Use
@ResourceIntent for partial same-resource maintenance flows that are more specific than generic CRUD but still belong to the same resource contract.
- Use
@UiSurface for discoverable UI experiences, read projections, related tabs, or embedded flows. A surface must point to a real resource/operation/schema path; it must not inline private SQL, HADES, ROWID, empresa, usuario, or session details.
- Use
@WorkflowAction only for business commands such as approve, cancel business state, reopen, publish, generate pending work, or other non-CRUD commands with their own payload, availability, and parity evidence. Do not promote Duplicar to @WorkflowAction by name alone; ordinary duplicate remains duplicate-draft + POST.
- Expose availability through the canonical Praxis capability/action/surface machinery. For Ergon/HADES decisions, use the existing HADES starter/
HadesLegacyAccessGuard/legacy bridge plus optional Praxis extension points such as ActionAvailabilityRule, SurfaceAvailabilityRule, and ResourceStateSnapshotProvider. Fail closed and expose only public availability, never the HADES/SQL/user/company reason.
Use these route safety states for write-like operations:
READ_PRAXIS_SAFE: read/options behavior can be delivered by the standard Praxis metadata/API platform surface with parity evidence.
WRITE_TABLE_DIRECT_CANDIDATE: direct platform/table write may be viable, but audit/parity is not closed.
WRITE_TABLE_DIRECT_SAFE: direct platform/table write is approved for the exact operation because evidence proves no required rule/side effect is skipped, or all required behavior is covered by triggers/constraints/defaults/session-safe infrastructure and parity.
WRITE_DB_BACKED_REQUIRED: the operation must use the validated DB-backed/legacy route to preserve behavior.
WRITE_BLOCKED: missing or contradictory evidence prevents implementation.
WRITE_DEFERRED: intentionally out of scope with risk recorded.
WRITE_TABLE_DIRECT_CANDIDATE does not authorize Java implementation. WRITE_TABLE_DIRECT_SAFE must be recorded in write-route-decision.md, write-contract.md, write-parity-matrix.md, and the phase gate.
Run the Praxis metadata/API contract review whenever a phase designs or changes DTOs, FilterDTOs, command DTOs, options, OpenAPI schemas, @UISchema, or @Filterable. Use praxis-dto-annotations for DTO annotation/metadata semantics and ergon-fieldspec-ui-contract for FieldSpec/Angular schema consumption. Also use praxis-java-host-project when creating or changing Java/Spring resources, and praxis-resource-entity-lookup-backend when the contract includes RESOURCE_ENTITY, OptionSourceRegistry, OptionSourceDescriptor, or /option-sources/{sourceKey}. The gate covers the API/schema/options contract.
When local migration docs provide docs/migracao/backend-praxis-first-playbook.md,
use it before Java contract or implementation work to choose the narrowest
backend shape: read-only resource, create/update resource, legacy-backed
resource, duplicate draft + POST, related @UiSurface, @WorkflowAction,
governed option source, dashboard/analytics resource, host/security boundary,
no backend mutation, blocked, or deferred. When the shape decision must be
auditable in a screen package, copy
docs/migracao/backend-praxis-first-checklist-template.md to
docs/migracao/<SCREEN>/backend-praxis-first-checklist.md and record the
operation state, Phase 1.5 decision, Praxis/Ergon resources reused, public
contract guardrails, route safety, and minimum validation. Do not use this
checklist to skip a phase or to promote a reference case; Phase 8 reference
promotion still uses backend-praxis-reference-audit.md and the reference
checklist.
Parte 1 Scope
The Parte 1 scope is generating Java/Spring read and write APIs. It is the active backend/API scope for Phases 0-8. UI, dashboard, and rule-migration tracks are coordinated by this orchestration but executed by their specialized skills after the required backend gates are closed.
In this scope:
- the Praxis metadata/API contract review validates DTO, FilterDTO, command DTO, options, OpenAPI/schema, and
@UISchema contracts exposed by the backend, and must record whether praxis-dto-annotations, ergon-fieldspec-ui-contract, praxis-java-host-project, and praxis-resource-entity-lookup-backend were applied or explicitly not applicable.
- Endpoint readiness means API execution evidence plus legacy/API/database parity.
- Phase 7 compares the authenticated legacy behavior against implemented endpoints and database effects.
- Phase 8 produces
backend-api-handoff.md or pilot-handoff.md.
- After Phase 8, the next recommended track may be Angular/UI wiring, dashboard/analytics materialization, Rule Migration Parte 2, or backend hardening. Choose from the closed gate and residuals; do not continue into UI or rules from an implicit assumption.
- When a Phase 8 backend screen is intended to become a reusable Praxis
reference case, require
backend-praxis-reference-audit.md. If
docs/migracao/backend-praxis-reference-quick-guide.md exists, use it first
to choose the reference shape; then read
docs/migracao/backend-praxis-reference-playbook.md for the detailed
boundary and create the audit from
docs/migracao/backend-praxis-reference-audit-template.md when present,
instead of copying the newest pilot blindly. The
phase-8-execution-gate.md must record whether backend reference promotion is
intended, which shape was selected, the audit state, whether the package may
enter the quick guide/playbook as a reusable reference, the allowed wording
when the state is NOT_REFERENCE_READY, the global guide checker result, and
any gap that prevents unrestricted reuse. A functional Phase 8 handoff
without this audit must not be advertised as a reusable Praxis backend
exemplar. The
current validated baseline is: ERGadm00034 for partial mutable resource
plus related surface, ERGadm00036 for controlled CRUD pilot, ERGadm00038
for an advanced scoped pilot with CRUD, canonical @WorkflowAction and
read-only related @UiSurface, ERGadm00039 for master-detail parent/child
CRUD, ERGadm00069 for mature CRUD pilot with browser replay, duplicate
draft and cancel/no-op proof, and ERGadm00229 for the scoped shared
legal-document related-write slice. Full ERGadm00229 remains
not-reference-ready. ERGadm00235 is a Phase 8 validated
NOT_REFERENCE_READY control package for blocked calendario create/update
boundaries; use it for learning what is missing, not as an implementation
baseline. Treat all reusable cases as bounded references, not unrestricted
full-screen templates.
Before copying or promoting a backend reference, validate the selected screen
with tools/migration-factory/validate-phase-gate.ps1 -Screen <SCREEN> -Phase 8 -MigrationRoot docs/migracao and
tools/migration-factory/check-praxis-semantic-contract.ps1 -ScreenPath docs/migracao/<SCREEN> -Strict. For a complete baseline refresh, run the
quick-guide loop over ERGadm00034, ERGadm00036, ERGadm00038,
ERGadm00039, ERGadm00069, ERGadm00229, and ERGadm00235, then run the
strict semantic check over docs/migracao. If validation fails, do not
promote the example; fix or downgrade the audit/gate first. If strict
validation reports BACKEND_REFERENCE_GUIDE_PROMOTES_NOT_READY, treat it as
guide/audit drift: a screen whose audit is NOT_REFERENCE_READY was described
as a reusable reference or implementation baseline. Correct the quick
guide/playbook wording to non-reference/control learning material, or reopen
the screen audit and Phase 8 gate before promotion.
Denied/restricted-user fixtures are not per-screen blockers for migration.
For screens governed by the shared HADES/security bridge
(ergon-hades-security-starter, ergon-legacy-bridge,
HadesLegacyAccessGuard, ErgonLegacyExecutor or equivalent), absence of a
real denied principal must be recorded as waived/accepted risk or
closed_by_bridge_contract, not as Blocked. Never claim proven 403 parity
without an executed denied fixture. Reopen as blocking only when the screen
bypasses the shared guard/bridge, exposes company/user/profile/session context
publicly, implements custom security outside HADES, or product explicitly
requires a proven 403 release gate.
For a new screen, do not assume docs/migracao/<SCREEN> already exists. If the package or migration-plan.md is missing, create the initial screen package, produce migration-plan.md, produce phase-0-execution-gate.md, and keep the phase at Phase 0 until the intake target, backend module candidates, repository access, Oracle connection status, XML/export source status, legacy app/browser access, evidence-source availability, initial expected operations, risks, and next prompt are explicit. Phase 0 does not close the real functional scope; Phase 1 does that from observed legacy evidence and operation-inventory.md. Verify every cited local evidence path before presenting it as available; if a historical artifact exists only in Git history or is missing from the working tree, mark it as HEAD-only, missing, or unconfirmed instead of treating it as a local source. Do not start Phase 1, API contract, or Java implementation from the first prompt unless the user explicitly provides equivalent Phase 0 evidence.
Phase 0 is operational preparation for Phase 1. Before closing it, try to open the legacy .tp route, try to download/export the screen XML from the legacy app when credentials/session allow it, identify any local/classpath XML fallback, and test Oracle with a simple read-only probe when database credentials are available. If any of these cannot be done, record the exact blocker, impact on Phase 1, and next action. A Phase 0 with no usable XML/export/local fallback, no legacy browser access, and no Oracle access must be Blocked, not Ready.
Phase 0 must also record the canonical migration workspace root and backend
module root candidates. If multiple roots resolve to the same module
directory/artifactId, such as migracao/ and migracao-package/, close Phase
0 as Blocked or Ready for next phase with adjustments only after the
canonical root is explicit and all later edit commands point to that root.
When the repository provides tools/migration-factory/download-runtime-xml.ps1, use it as the preferred deterministic path for .xml runtime export before hand-written browser-text extraction. It parses the login form, resolves form action, keeps cookies in memory, validates the saved file with an XML parser, and writes sanitized evidence. Provide credentials only through an already-created PSCredential object or pre-existing environment variables such as ERGON_LEGACY_USER and ERGON_LEGACY_PASSWORD; never put literal secrets in the command. If the helper returns RUNTIME_LOGIN_SAFE_INJECTION_REQUIRED, then use browser login/manual login or ask for a safe credential injection path.
Legacy browser authentication is part of Phase 0 when credentials are provided in the active user message or the active private session. Do not stop at an unauthenticated HTTP 401/403 probe and defer login to Phase 1. First try to establish an authenticated browser/app session, then reopen the .tp route and retry the .xml export/download using the authenticated session/cookies. Never write credentials, passwords, tokens, or cookies to artifacts. Record only credential/session status such as available in active session, login attempted, login succeeded, login failed, MFA/manual login required, export forbidden after authenticated login, or browser automation unavailable.
For Cronos/Archon demo-style login, do not treat HttpOnly cookies as a blocker by itself. If the unauthenticated .tp returns a login HTML with a SESSION cookie and a login form, parse the actual <form action> and resolve it against the response URL using normal URL resolution. For example, action="/login" on http://host/Ergon/Administracao/SCREEN.tp means http://host/login, not http://host/Ergon/login. Do not invent /Ergon/login, /Administracao/login, or other login paths unless the HTML action or redirect actually points there.
Use an in-memory HTTP session/cookie container to:
- request the
.tp route and retain the SESSION cookie only in memory;
- submit credentials to the resolved form action with the form field names observed in the HTML, commonly
username and password;
- request the matching
.xml route with the same in-memory session;
- save the XML only if the response is XML for the requested transaction and the saved file parses as XML, then record path, HTTP status, content type, byte size, SHA-256, parser result, and timestamp.
Do not write the username, password, cookie, Authorization header, request body, or connection string into artifacts, logs, command transcripts, screenshots, or generated scripts. Do not place credential literals in shell commands or reusable scripts. Prefer credentials already available through a local secrets/env file, environment variables, or the active browser login path.
If credentials are present only in the active conversation/session and no non-recording shell injection path exists, do not give up immediately. First use the in-app browser or Chrome login form when available, because typing into the authorized login page does not require putting the secret in a shell transcript. After browser login succeeds, retry .tp and .xml from the authenticated browser/session. If browser automation cannot submit the login safely, ask the user to log in manually or provide a safe credential injection method. Only then mark RUNTIME_LOGIN_SAFE_INJECTION_REQUIRED, XML_RAW_EXPORT_NOT_SAVED, RUNTIME_XML_EXPORT_AUTH_BLOCKED, or a similar residual.
Even when credentials cannot be submitted, parse the unauthenticated login HTML when available and record sanitized login mechanics: form action resolved URL, method, field names, HTTP status, and whether a SESSION cookie was issued. Do not record field values.
Never treat text copied from Chromium's XML viewer as raw XML unless it round-trips through an XML parser. The viewer can decode escaped markup inside attributes, for example valor="<div ...>" becoming valor="<div ...>", which makes the saved text invalid XML. If a browser-derived file fails XML parsing, classify it as RUNTIME_XML_BROWSER_TEXT_INVALID, keep it only as diagnostic evidence, and rely on a raw response body, authenticated HTTP export, local XML, or HADES/Cronos source for structural discovery.
Only classify .tp or .xml as a non-blocking Phase 0 residual after one of these is true: authenticated login succeeded and the route/export still failed; browser login was impossible for a documented reason; or the user did not provide usable credentials. If credentials are available but login was not attempted, keep Phase 0 Open or Blocked with RUNTIME_LOGIN_NOT_ATTEMPTED; do not close it as Ready for next phase with adjustments.
Phase 0 must not perform technical XML discovery. It may record that a local XML/export/database source candidate exists and, when cheap, confirm screen code/title. It must not extract or promote grid SQL, filters, binds, links, components, dataTable, write routes, Oracle objects, or field lineage; those belong to Phase 1. The Phase 0 readiness matrix lists only backend/API modules and libraries needed for Java/Spring APIs.
Scaffold or factory scripts are convenience helpers only. Do not depend on them as the source of truth for Phase 0. If a scaffold/factory is missing, broken, or points to an absent template, continue by creating migration-plan.md and phase-0-execution-gate.md from the canonical repository templates, and record a non-business tooling residual such as SCAFFOLD_UNAVAILABLE with path, impact, and next action. A missing scaffold must not silently relax Phase 0 evidence requirements, must not justify skipping Oracle/XML/browser checks, and must not be recorded as a blocker for the business migration unless no canonical templates are available.
Ordered Phases
Phase 0 - Operational Preparation
- Define the screen/functionality to investigate, target backend/API module candidates, environment, repository access, database access, XML/debug source, legacy app/browser access, credentials availability, and initial expected user operations using the Standard Legacy Operation Inventory.
- For Cronos/Archon screens, require a runtime XML export decision before Phase 1:
.tp reachability, matching .xml export/download result, credential/session status, export permission status, parser-valid saved XML status, local XML path candidate, and whether the source-of-truth check is ready, blocked, or deferred.
- If legacy credentials are available in the active session, attempt browser/app login before deciding
.tp or .xml status. Reopen .tp and retry .xml after login. When the login page exposes a login form, resolve its real action URL and try the same flow with an in-memory HTTP session to persist the raw XML export. An unauthenticated 401/403 alone is not enough to defer authenticated runtime capture.
- Test Oracle/banco with a simple read-only probe when credentials are available. Record the environment, success/failure, and whether Phase 1 can run Oracle/HADES checks.
- Treat local XML as a source candidate only in Phase 0. Do not parse component lineage, grid SQL, filters, links, write
dataTable, hidden fields, or route semantics in this phase.
- Record only backend/API repositories and shared libraries required for Java/Spring API migration. Do not include visual/UI libraries as Phase 0 dependencies.
- Do not store credentials in artifacts. Phase 0 may state that credentials are available for the active session, unavailable, invalid, or insufficient for XML export, but must not record usernames/passwords/secrets.
- If credentials or authenticated runtime access are unavailable, close Phase 0 only with an explicit
RUNTIME_AUTH_BLOCKED or RUNTIME_XML_EXPORT_AUTH_BLOCKED residual carried into Phase 1.
- Treat scope as provisional in this phase. The real migration scope is closed in Phase 1 after observed legacy evidence.
- Output:
migration-plan.md.
- Closeout:
phase-0-execution-gate.md.
Phase 1 - Legacy Screen Operation Inventory
- Use
ergon-archon-screen-discovery.
- Close browser/XML/runtime SQL, component lineage, read data sources, keys, authorization, session context, visible actions, related links, and write surface discovery for every standard operation.
- When a local legacy XML exists, require an explicit source-of-truth artifact before closing Phase 1: produce
cronos-source-of-truth.md comparing local XML evidence against authenticated runtime/debug evidence and HADES/Oracle registry or stored-resource candidates. For Cronos/ErgonNG, treat XML as import/export for database-persisted page structure; check transaction, controls, properties, screen pattern/customization tables, and user screen pattern before accepting the local XML. Keep local XML at CONFIRMED_LOCAL_SOURCE until runtime/HADES equivalence is proven. If HADES/Oracle is unavailable, the artifact must exist with a Blocked or Partial decision and the exact rerun command/query.
- For Cronos bind semantics, do not block only on Chrome/browser automation when XML plus Oracle metadata can answer the question. If
sqlParameters, the SQL predicate, a reused component or equivalent screen, and Oracle metadata/view source close the value semantics, record the bind as BIND_SEMANTICS_CLOSED_BY_XML_ORACLE and classify it as public filter, server-side scope, constant bind, parent-row context, or internal runtime parameter. Use docs/migracao/phase1-cronos-bind-resolution-standard.md when present. For standard Cronos recordPanelEdit + dataTable, XML plus local Cronos framework source may close create/update payload as SOURCE_DERIVED_PAYLOAD_READY_FOR_DB_PROBE; browser/runtime remains mandatory for visible workflow, action state, restricted users, final parity, and non-standard write actions whose payload is not source-derived.
- If the browser workflow is not fully operated by Codex, require
runtime-capture-form.md so the developer has a structured way to provide the missing visible/runtime facts. browser-runtime.md alone is not enough when it only infers behavior from XML. For process validation before developer handoff, an unoperated or partial visual workflow blocks Phase 1 readiness; do not close Phase 1 as Ready for next phase or Ready for next phase with adjustments while default load, runtime binds, selected-row/public-key proof, visible action state, and representative non-empty fixture/context are missing.
- When the workspace provides
docs/migracao/phase1-scope-authorization-standard.md, apply it before Phase 1 handoff. allowed-default-context may close from authenticated browser default load, non-empty fixture, selected-row public key, 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 evidence shows a bypass of HadesLegacyAccessGuard/equivalent, ErgonLegacyExecutor/equivalent, public exposure of company/user/profile/security context, or custom security outside HADES. When the factory provides new-phase1-scope-authorization-decision-pack.ps1, generate the decision pack only for genuinely open scope/authorization cases; it structures owner approval/blocker evidence but does not make the gate Ready by itself. Do not expose company/user/profile/session context as public FilterDTO, schema, URL, option payload, or x-ui fields.
- Require HADES registry/access/stored-resource coverage before Phase 1 can close. This can be executed evidence or an explicit blocked SQL/helper artifact, but a gate with
HADES_REGISTRY_NOT_CHECKED must not advance to Phase 1.5.
operation-inventory.md must use deterministic states (Implemented, Ready, Candidate, Blocked, Deferred, Not present) instead of generic Unknown.
- Output:
investigation.md, component-lineage-matrix.md, browser-runtime.md, runtime-capture-form.md when needed, cronos-source-of-truth.md, `legacy-doc-
…(truncated)
1---2name: ergon-migration-orchestration3description: Orchestrate complex Ergon/Archon legacy-to-Praxis migrations across ordered tracks. Use when Codex must plan, audit, gate, or coordinate screen discovery, table rule audit, read/write API migration, UI wiring readiness, dashboard or rule-migration routing, parity testing, handoff artifacts, or when the user asks what phase/skill should run next.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/ergon-migration-orchestration6---78# Ergon Migration Orchestration910## Derived Discovery Matrix1112Before prioritizing a screen, selecting a reusable pilot, or resuming a screen13whose gate predates the current migration cut, run14`tools/migration-factory/export-praxis-screen-discovery-matrix.ps1` when it is15available and inspect the record for that screen. Use it only as a derived16operational index for resource candidates, gates, read/write state, Angular17runtime shape and next-action candidates. The phase gate, versioned contracts,18Praxis annotations and live canonical surfaces remain the sources of truth.1920After a material phase closure, regenerate the matrix before changing portfolio21priority or promoting a screen as reference. Do not infer primary intent from22matrix labels or text; resolve the canonical resource, operation, action or23surface in its owner artifact first.2425Use this skill as the top-level conductor for Ergon/Archon migrations. It does not replace the specialized skills; it decides the order, required artifacts, phase gates, and next action. When a phase enters a domain owned by another skill, route to that skill and preserve its gates instead of restating or weakening them here.2627## Core Rule2829Never let a later phase compensate for missing evidence from an earlier phase silently. If an artifact is missing, either produce it now with the right skill or mark the phase as blocked with the exact gap.3031Before changing code, contracts, templates, or migration artifacts, apply the32root migration `AGENTS.md` platform governance. Classify the change as33`docs-apenas`, `local-pequena`, `transversal`, `contrato-publico`, or34`arquitetural`; identify the canonical owner; and record the impact map when35the change touches public contract, multiple consumers, or architecture.3637Before editing Java, Angular, module-owned docs/tests, or running a generator38against a target module, run the duplicate-module-root guard when a module39name/artifactId is known. Do not use this guard as a Phase 0 prerequisite for40creating workspace-owned screen artifacts under `docs/migracao/<SCREEN>`; run41it before the first module-owned edit instead:4243```bash44python3 codex-skills/ergon-migration-orchestration/scripts/check_duplicate_module_roots.py \45 --workspace-root <canonical-migracao-root-from-AGENTS> \46 --module <module-directory-or-artifactId> \47 --current-root <intended-edit-root>48```4950If the current root is the canonical module under the canonical workspace,51duplicates outside that workspace (for example historical clones or issue52worktrees such as `m79/<module>`) are advisory: continue in the canonical root53without asking for human confirmation. The guard must still block when the54current root is noncanonical, when another matching root exists inside the55canonical workspace, or when the canonical root is outside a git checkout. If56it returns `MIGRATION_MODULE_ROOT_GUARD_BLOCKED`, stop before the module-owned57edit and use the canonical root from `AGENTS.md` or require an explicit human58choice. Its message must remain sanitized: no credentials, users, company59identifiers, headers, cookies, or environment secret values.6061## Skill Lock Drift Triage6263When the migration workspace lock audit reports only a source commit mismatch,64do not spend the intake turn re-reading every installed copy or block creation65of the Phase 0 screen package automatically. Audit the selected canonical skill66family and its installed projection first:6768- if source hashes match the family manifest and the selected installed skill69 matches the canonical tree, record `CODEX_SKILLS_LOCK_DRIFT` as a non-blocking70 tooling residual and continue workspace-owned Phase 0 work;71- if the selected source is invalid or its installed projection differs, repair72 the canonical manifest/sync before relying on the skill, and keep73 module-owned edits blocked until that reconciliation passes;74- never update a workspace lock to represent uncommitted source changes. Refresh75 the pin only after the canonical skill changes are committed.7677A commit-only lock mismatch is still relevant before versioning or handoff, but78it must not cause a new-screen intake to end without its Phase 0 artifacts when79the selected skill tree itself is proven current.8081Do not solve Praxis platform gaps by inventing Ergon-local semantics. If the82issue belongs to `praxis-ui-angular`, `praxis-metadata-starter`, or83`praxis-config-starter`, create a `Praxis Platform Follow-up` with objective84evidence and a prompt for the Praxis specialist. A temporary Ergon workaround85must have an owner, removal trigger, canonical replacement, and must prevent86the screen from being treated as a scalable example while it exists.8788Every phase closeout must produce a reusable gate packet: final decision, evidence actually executed, residual issues with owners, explicit return-to-previous-phase rules, and the next recommended prompt/skill. If the screen advances with non-blocking residuals, classify it as `Ready for next phase with adjustments` and carry those residuals into the next phase and handoff.8990Endpoint readiness is not a static-test decision. Do not call an endpoint `Verified` or promote it to handoff solely because unit tests, OpenAPI generation, schema assertions, or mocked service tests passed. For backend API handoff, require executed endpoint evidence plus legacy/API/database comparison with the same user/company/context and filters. If any part was not executed, use a narrower state such as `Implemented with automated tests`, `Schema/static contract passed`, `Executed endpoint smoke`, `Legacy parity pending`, `Blocked`, or `Deferred`.9192For write operations, classify the route per operation instead of assuming either generic CRUD or DB-backed by default. The conservative default is: unknown rule, context, route, side effect, or error behavior means `WRITE_DB_BACKED_REQUIRED` or `WRITE_BLOCKED`. Direct table/Praxis CRUD can be approved only as `WRITE_TABLE_DIRECT_SAFE` when Phase 4/5 evidence proves it preserves required behavior, errors, session context, side effects, and parity.9394## Development Migration Mutation Authority9596When the migration workspace provides97`docs/migracao/development-mutation-authority.md`, treat its declared98development database as persistently pre-approved for data mutation required by99migration. Do not ask for a new human confirmation per screen, API call,100marker, fixture, existing development row, cleanup, or retry. Execute the101technical preflight, use a disposable fixture where practical, restore the102baseline when an existing row is required, and record sanitized evidence.103104This authority is not a shortcut around the write gates. `WRITE_DB_BACKED_REQUIRED`,105`WRITE_TABLE_DIRECT_SAFE`, `WRITE_BLOCKED`, and `WRITE_DEFERRED` still decide106which API route can be implemented or handed off. They must never be confused107with permission to run the controlled probe that produces the missing evidence.108Only an environment mismatch, unavailable connection/credential, unknown route,109or legacy/HADES rejection is a mutation blocker; record that technical fact110instead of asking whether mutation is allowed.111112## Track Boundaries113114This skill coordinates tracks; it does not make local substitutes for canonical Praxis skills or runtimes.115116- **Backend/API Parte 1**: Phases 0-8 cover legacy evidence, platform reuse inventory, read/options API, write audit/contract/implementation, parity, and backend handoff. Use `ergon-archon-screen-discovery`, `ergon-archon-read-api-migration`, `ergon-table-rule-audit`, `ergon-archon-write-api-migration`, `praxis-dto-annotations`, `praxis-java-host-project`, and `praxis-resource-entity-lookup-backend` as required by the phase.117- **Angular/UI Native Praxis track**: Starts only from a closed backend handoff, scoped pilot handoff, or explicit backend gap package. Use `ergon-angular-ui-screen-wiring` and the general Praxis UI skills it requires. UI work must consume canonical schemas, capabilities, HATEOAS links, actions, surfaces, option sources, and `@praxisui/*` runtime behavior; it must not introduce an Ergon-local action/surface/lookup/form/table runtime.118- **Dashboard/analytics track**: When the target is dashboard, KPI, cockpit, analytics, charts, stats, or aggregate metrics, route to `ergon-dashboard-praxis-charts` plus `praxis-dashboard-analytics`. Do not model metrics as ordinary screen fields when the canonical analytics contract is required.119- **Rule migration Parte 2**: Starts only after the relevant Parte 1 baseline is closed and the rule scope has table-rule evidence, read/write boundaries, and parity residuals explicit. Use `ergon-rule-migration-orchestration`; if it finds missing API, write, HADES, shadow-mode, or parity evidence, return to the exact Parte 1 phase that owns the gap.120121Every cross-track handoff must state the selected skill, required inputs, expected outputs, residuals carried forward, and the return-to-previous-track rule.122123## Canonical Phase Management Artifacts124125Use these files to make phase state deterministic across agents and developers:126127- `docs/migracao/<SCREEN>/phase-<PHASE-ID>-execution-gate.md`: required whenever a phase is classified as `Ready for next phase`, `Ready for next phase with adjustments`, `Blocked`, or `Deferred`. This file is the phase closeout; do not treat a functional artifact such as `quality-round-2.md` as a substitute.128- `docs/migracao/<SCREEN>/phase-<PHASE-ID>-<slug>-plan.md`: optional planning/reentry artifact. Use it before execution when scope is partial, a previous gate carried residuals, fixtures are conditional, browser/API/Oracle evidence must be coordinated, mutation risk exists, or a phase is resumed after an earlier closeout. A plan is not execution evidence and is not a gate closeout.129130`<PHASE-ID>` uses dots converted to hyphens: Phase 1.5 is `1-5`.131132When the user explicitly asks for planning only, create or update a `phase-<PHASE-ID>-<slug>-plan.md` and leave the phase state `Open`. When evidence has been executed or a phase decision is made, create or update the standalone `phase-<PHASE-ID>-execution-gate.md`.133134## Short Continuation Commands135136If the latest phase gate is `Ready for next phase` or `Ready for next phase with adjustments`, a short user command such as `continuar`, `seguir`, `ok`, `1`, or `proximo` is enough to start the next recommended phase.137138When handling a short continuation command:1391401. Locate the latest `docs/migracao/<SCREEN>/phase-<PHASE-ID>-execution-gate.md`.1412. Confirm its state is `Ready for next phase` or `Ready for next phase with adjustments`.1423. Read the gate's `Continuacao Curta` or next-step section as the source of truth.1434. Start the recommended next phase with the recommended skill and required input artifacts; do not stop after merely restating the prompt when the gate is unambiguous.1445. Carry residuals from the gate into the new phase.1456. Do not ask the user for a long prompt unless the gate is missing, ambiguous, `Blocked`, `Deferred`, or points to multiple possible next phases.146147Short continuation is not automatic chaining. The user still needs to send a follow-up command, but it may be short because the gate is the source of truth.148149Every phase gate that closes as `Ready for next phase` or `Ready for next phase with adjustments` must include a complete short-continuation contract: next phase, skill, required inputs, expected outputs, carried residuals, and the exact execution intent. If any of those fields is missing, treat the next short command as a request to repair/clarify the gate before running the next phase.150151## Standard Legacy Operation Inventory152153Treat Ergon/Archon screens as framework-driven until evidence proves otherwise. At intake and discovery time, create an operation inventory for the screen using this baseline:154155- `Consultar/listar`: default grid/list load, filters, pagination, sorting, empty result, company/user scope.156- `Ler detalhe`: row selection, detail panel, nested detail form, public key, internal `ROWID`/locator strategy.157- `Novo/Salvar`: create mode, defaults, required fields, validation messages, generated DML routine/table route, success side effects, cleanup.158- `Editar/Salvar`: update mode, immutable keys, changed-field payload, validation messages, side effects.159- `Apagar`: delete/anulation button, confirmation dialog, permission/dependency blockers, cleanup and row preservation proof.160- `Duplicar`: copied/defaulted fields, new-key strategy, save route, duplicate validation.161- `Cancelar`: no-mutation behavior from create/edit/duplicate modes.162- `Documentos legais`: legal-document tab/block, linked component/screen, `PONTLEI`/document locators, read/write scope.163- `Publicacoes/atos` and `Pendencias`: include when visible, linked, or reached by triggers/packages, even if deferred from the current slice.164165For every operation, record one of: `Implemented`, `Ready`, `Blocked`, `Deferred`, or `Not present`. Do not expose or hand off an operation unless its backend/API state is `Implemented` with parity evidence or intentionally blocked/deferred.166167## Standard Praxis Metadata/API Mapping168169For every operation in the inventory, map the legacy behavior to the new platform surface before implementation:170171| Legacy operation | New platform/Praxis surface | Required migration decision |172| --- | --- | --- |173| `Consultar/listar` | `POST /<resource>/filter`; `BaseResourceService.filterWithIncludeIds`; DTO/FilterDTO metadata | Implement filters, paging, sort, scope, authorization, empty state, and parity cases. |174| `Ler detalhe` | `GET /<resource>/{id}`; `BaseResourceService.findById`; optionally `GET /by-ids` / `findAllById` | Choose stable public ID; keep `ROWID` internal unless explicitly accepted. |175| Lookups/options | `POST /<resource>/options/filter`; `GET /options/by-ids`; `OptionDTO`; `@UISchema(endpoint, filterField, sortField, optionsPageSize)` | Implement combo semantics and selected-value reloads used by the UI. |176| `Novo/Salvar` | `POST /<resource>`; `BaseResourceService.save` | Use direct platform save only when safe; otherwise route through a screen-specific legacy-backed service under the shared Ergon bridge. |177| `Editar/Salvar` | `PUT /<resource>/{id}`; `BaseResourceService.update` | Use command DTOs when read DTOs contain derived/internal fields; preserve legacy validation and side effects. |178| `Apagar` | `DELETE /<resource>/{id}`; `BaseResourceService.deleteById`; batch delete only when explicitly closed | Prove confirmation, permission, dependency blockers, no-mutation failures, and cleanup. |179| `Duplicar` | `POST /<resource>/{id}/duplicate-draft`; `DuplicateDraftResourceService.duplicateDraft`; `DuplicateDraftUtils`; `@UISchema(copyOnDuplicate)` | Generate an editable draft, then persist through `POST`; do not assume every copied field is allowed. Use `@WorkflowAction` only if runtime proves duplicate is a business command with its own immediate effect or dedicated workflow route. |180| `Cancelar` | No backend mutation | Record no-op proof and avoid adding a backend mutation endpoint. |181| `Documentos legais` | Separate related resource or linked component API using the same filter/detail/write pattern | Resolve link keys such as `PONTLEI` server-side and scope write only after parity is closed. |182| `Publicacoes/atos` / `Pendencias` | Separate related resource/workflow API; often backed by reusable legacy blocks or related transactions | Do not fold into the main resource unless XML/runtime evidence proves the same route. |183184All resources must also expose or deliberately block the relevant schema and action metadata: `/schemas`, `/schemas/filtered`, `@UISchema`, HATEOAS/action links, and explicit `405`/`501` or omitted routes for unsupported operations. For legacy-backed reads/writes that depend on Oracle package state, keep the Praxis metadata/API controller/service contract while placing same-connection `HADES.FLAG_PACK` setup, cleanup, procedure calls, and Oracle error translation behind the shared Ergon bridge.185186Praxis semantic contract rules for Ergon:187188- Treat the resource endpoint, DTO, FilterDTO, schemas, options, `_links`, `/actions`, `/surfaces`, and `/capabilities` as one contract. Do not create parallel capability/action models for Ergon screens.189- Before creating a new endpoint, launcher, adapter, metadata field, action, surface, capability, option source, or Angular component, inventory the native Praxis support and classify the need as `ja-suportado-so-ux`, `ja-suportado-mal-nomeado-ou-mal-materializado`, `suportado-parcialmente`, or `lacuna-real-de-contrato`. Only `lacuna-real-de-contrato` justifies a new Praxis contract request.190- Use the canonical owner map: `praxis-metadata-starter` owns `x-ui`, schemas, HATEOAS, actions, surfaces, capabilities, annotations, and resource-oriented metadata; `praxis-config-starter` owns `/api/praxis/config/**`, user config, AI registry, templates, ETag, and AI authoring contracts; `praxis-ui-angular` owns the official Angular runtime, components, adapters, launchers, materializers, editors, and dynamic fields; `praxis-api-quickstart` is an operational reference, not the semantic owner.191- Keep simple create/update/delete as resource operations when the write gate proves they are safe. Do not mark `POST`, `PUT`, or `DELETE` as `@WorkflowAction` only because the legacy UI had a button.192- Use `@ResourceIntent` for partial same-resource maintenance flows that are more specific than generic CRUD but still belong to the same resource contract.193- Use `@UiSurface` for discoverable UI experiences, read projections, related tabs, or embedded flows. A surface must point to a real resource/operation/schema path; it must not inline private SQL, HADES, `ROWID`, empresa, usuario, or session details.194- Use `@WorkflowAction` only for business commands such as approve, cancel business state, reopen, publish, generate pending work, or other non-CRUD commands with their own payload, availability, and parity evidence. Do not promote `Duplicar` to `@WorkflowAction` by name alone; ordinary duplicate remains `duplicate-draft + POST`.195- Expose availability through the canonical Praxis capability/action/surface machinery. For Ergon/HADES decisions, use the existing HADES starter/`HadesLegacyAccessGuard`/legacy bridge plus optional Praxis extension points such as `ActionAvailabilityRule`, `SurfaceAvailabilityRule`, and `ResourceStateSnapshotProvider`. Fail closed and expose only public availability, never the HADES/SQL/user/company reason.196197Use these route safety states for write-like operations:198199- `READ_PRAXIS_SAFE`: read/options behavior can be delivered by the standard Praxis metadata/API platform surface with parity evidence.200- `WRITE_TABLE_DIRECT_CANDIDATE`: direct platform/table write may be viable, but audit/parity is not closed.201- `WRITE_TABLE_DIRECT_SAFE`: direct platform/table write is approved for the exact operation because evidence proves no required rule/side effect is skipped, or all required behavior is covered by triggers/constraints/defaults/session-safe infrastructure and parity.202- `WRITE_DB_BACKED_REQUIRED`: the operation must use the validated DB-backed/legacy route to preserve behavior.203- `WRITE_BLOCKED`: missing or contradictory evidence prevents implementation.204- `WRITE_DEFERRED`: intentionally out of scope with risk recorded.205206`WRITE_TABLE_DIRECT_CANDIDATE` does not authorize Java implementation. `WRITE_TABLE_DIRECT_SAFE` must be recorded in `write-route-decision.md`, `write-contract.md`, `write-parity-matrix.md`, and the phase gate.207208Run the Praxis metadata/API contract review whenever a phase designs or changes DTOs, FilterDTOs, command DTOs, options, OpenAPI schemas, `@UISchema`, or `@Filterable`. Use `praxis-dto-annotations` for DTO annotation/metadata semantics and `ergon-fieldspec-ui-contract` for FieldSpec/Angular schema consumption. Also use `praxis-java-host-project` when creating or changing Java/Spring resources, and `praxis-resource-entity-lookup-backend` when the contract includes `RESOURCE_ENTITY`, `OptionSourceRegistry`, `OptionSourceDescriptor`, or `/option-sources/{sourceKey}`. The gate covers the API/schema/options contract.209210When local migration docs provide `docs/migracao/backend-praxis-first-playbook.md`,211use it before Java contract or implementation work to choose the narrowest212backend shape: read-only resource, create/update resource, legacy-backed213resource, duplicate draft + POST, related `@UiSurface`, `@WorkflowAction`,214governed option source, dashboard/analytics resource, host/security boundary,215no backend mutation, blocked, or deferred. When the shape decision must be216auditable in a screen package, copy217`docs/migracao/backend-praxis-first-checklist-template.md` to218`docs/migracao/<SCREEN>/backend-praxis-first-checklist.md` and record the219operation state, Phase 1.5 decision, Praxis/Ergon resources reused, public220contract guardrails, route safety, and minimum validation. Do not use this221checklist to skip a phase or to promote a reference case; Phase 8 reference222promotion still uses `backend-praxis-reference-audit.md` and the reference223checklist.224225## Parte 1 Scope226227The Parte 1 scope is generating Java/Spring read and write APIs. It is the active backend/API scope for Phases 0-8. UI, dashboard, and rule-migration tracks are coordinated by this orchestration but executed by their specialized skills after the required backend gates are closed.228229In this scope:230231- the Praxis metadata/API contract review validates DTO, FilterDTO, command DTO, options, OpenAPI/schema, and `@UISchema` contracts exposed by the backend, and must record whether `praxis-dto-annotations`, `ergon-fieldspec-ui-contract`, `praxis-java-host-project`, and `praxis-resource-entity-lookup-backend` were applied or explicitly not applicable.232- Endpoint readiness means API execution evidence plus legacy/API/database parity.233- Phase 7 compares the authenticated legacy behavior against implemented endpoints and database effects.234- Phase 8 produces `backend-api-handoff.md` or `pilot-handoff.md`.235- After Phase 8, the next recommended track may be Angular/UI wiring, dashboard/analytics materialization, Rule Migration Parte 2, or backend hardening. Choose from the closed gate and residuals; do not continue into UI or rules from an implicit assumption.236- When a Phase 8 backend screen is intended to become a reusable Praxis237 reference case, require `backend-praxis-reference-audit.md`. If238 `docs/migracao/backend-praxis-reference-quick-guide.md` exists, use it first239 to choose the reference shape; then read240 `docs/migracao/backend-praxis-reference-playbook.md` for the detailed241 boundary and create the audit from242 `docs/migracao/backend-praxis-reference-audit-template.md` when present,243 instead of copying the newest pilot blindly. The244 `phase-8-execution-gate.md` must record whether backend reference promotion is245 intended, which shape was selected, the audit state, whether the package may246 enter the quick guide/playbook as a reusable reference, the allowed wording247 when the state is `NOT_REFERENCE_READY`, the global guide checker result, and248 any gap that prevents unrestricted reuse. A functional Phase 8 handoff249 without this audit must not be advertised as a reusable Praxis backend250 exemplar. The251 current validated baseline is: `ERGadm00034` for partial mutable resource252 plus related surface, `ERGadm00036` for controlled CRUD pilot, `ERGadm00038`253 for an advanced scoped pilot with CRUD, canonical `@WorkflowAction` and254 read-only related `@UiSurface`, `ERGadm00039` for master-detail parent/child255 CRUD, `ERGadm00069` for mature CRUD pilot with browser replay, duplicate256 draft and cancel/no-op proof, and `ERGadm00229` for the scoped shared257 legal-document related-write slice. Full `ERGadm00229` remains258 not-reference-ready. `ERGadm00235` is a Phase 8 validated259 `NOT_REFERENCE_READY` control package for blocked calendario create/update260 boundaries; use it for learning what is missing, not as an implementation261 baseline. Treat all reusable cases as bounded references, not unrestricted262 full-screen templates.263 Before copying or promoting a backend reference, validate the selected screen264 with `tools/migration-factory/validate-phase-gate.ps1 -Screen <SCREEN> -Phase265 8 -MigrationRoot docs/migracao` and266 `tools/migration-factory/check-praxis-semantic-contract.ps1 -ScreenPath267 docs/migracao/<SCREEN> -Strict`. For a complete baseline refresh, run the268 quick-guide loop over `ERGadm00034`, `ERGadm00036`, `ERGadm00038`,269 `ERGadm00039`, `ERGadm00069`, `ERGadm00229`, and `ERGadm00235`, then run the270 strict semantic check over `docs/migracao`. If validation fails, do not271 promote the example; fix or downgrade the audit/gate first. If strict272 validation reports `BACKEND_REFERENCE_GUIDE_PROMOTES_NOT_READY`, treat it as273 guide/audit drift: a screen whose audit is `NOT_REFERENCE_READY` was described274 as a reusable reference or implementation baseline. Correct the quick275 guide/playbook wording to non-reference/control learning material, or reopen276 the screen audit and Phase 8 gate before promotion.277278Denied/restricted-user fixtures are not per-screen blockers for migration.279For screens governed by the shared HADES/security bridge280(`ergon-hades-security-starter`, `ergon-legacy-bridge`,281`HadesLegacyAccessGuard`, `ErgonLegacyExecutor` or equivalent), absence of a282real denied principal must be recorded as `waived`/accepted risk or283`closed_by_bridge_contract`, not as `Blocked`. Never claim proven `403` parity284without an executed denied fixture. Reopen as blocking only when the screen285bypasses the shared guard/bridge, exposes company/user/profile/session context286publicly, implements custom security outside HADES, or product explicitly287requires a proven `403` release gate.288289For a new screen, do not assume `docs/migracao/<SCREEN>` already exists. If the package or `migration-plan.md` is missing, create the initial screen package, produce `migration-plan.md`, produce `phase-0-execution-gate.md`, and keep the phase at Phase 0 until the intake target, backend module candidates, repository access, Oracle connection status, XML/export source status, legacy app/browser access, evidence-source availability, initial expected operations, risks, and next prompt are explicit. Phase 0 does not close the real functional scope; Phase 1 does that from observed legacy evidence and `operation-inventory.md`. Verify every cited local evidence path before presenting it as available; if a historical artifact exists only in Git history or is missing from the working tree, mark it as `HEAD-only`, `missing`, or `unconfirmed` instead of treating it as a local source. Do not start Phase 1, API contract, or Java implementation from the first prompt unless the user explicitly provides equivalent Phase 0 evidence.290291Phase 0 is operational preparation for Phase 1. Before closing it, try to open the legacy `.tp` route, try to download/export the screen XML from the legacy app when credentials/session allow it, identify any local/classpath XML fallback, and test Oracle with a simple read-only probe when database credentials are available. If any of these cannot be done, record the exact blocker, impact on Phase 1, and next action. A Phase 0 with no usable XML/export/local fallback, no legacy browser access, and no Oracle access must be `Blocked`, not `Ready`.292293Phase 0 must also record the canonical migration workspace root and backend294module root candidates. If multiple roots resolve to the same module295directory/artifactId, such as `migracao/` and `migracao-package/`, close Phase2960 as `Blocked` or `Ready for next phase with adjustments` only after the297canonical root is explicit and all later edit commands point to that root.298299When the repository provides `tools/migration-factory/download-runtime-xml.ps1`, use it as the preferred deterministic path for `.xml` runtime export before hand-written browser-text extraction. It parses the login form, resolves `form action`, keeps cookies in memory, validates the saved file with an XML parser, and writes sanitized evidence. Provide credentials only through an already-created `PSCredential` object or pre-existing environment variables such as `ERGON_LEGACY_USER` and `ERGON_LEGACY_PASSWORD`; never put literal secrets in the command. If the helper returns `RUNTIME_LOGIN_SAFE_INJECTION_REQUIRED`, then use browser login/manual login or ask for a safe credential injection path.300301Legacy browser authentication is part of Phase 0 when credentials are provided in the active user message or the active private session. Do not stop at an unauthenticated HTTP `401`/`403` probe and defer login to Phase 1. First try to establish an authenticated browser/app session, then reopen the `.tp` route and retry the `.xml` export/download using the authenticated session/cookies. Never write credentials, passwords, tokens, or cookies to artifacts. Record only credential/session status such as `available in active session`, `login attempted`, `login succeeded`, `login failed`, `MFA/manual login required`, `export forbidden after authenticated login`, or `browser automation unavailable`.302303For Cronos/Archon demo-style login, do not treat `HttpOnly` cookies as a blocker by itself. If the unauthenticated `.tp` returns a login HTML with a `SESSION` cookie and a login form, parse the actual `<form action>` and resolve it against the response URL using normal URL resolution. For example, `action="/login"` on `http://host/Ergon/Administracao/SCREEN.tp` means `http://host/login`, not `http://host/Ergon/login`. Do not invent `/Ergon/login`, `/Administracao/login`, or other login paths unless the HTML action or redirect actually points there.304305Use an in-memory HTTP session/cookie container to:3063071. request the `.tp` route and retain the `SESSION` cookie only in memory;3082. submit credentials to the resolved form action with the form field names observed in the HTML, commonly `username` and `password`;3093. request the matching `.xml` route with the same in-memory session;3104. save the XML only if the response is XML for the requested transaction and the saved file parses as XML, then record path, HTTP status, content type, byte size, SHA-256, parser result, and timestamp.311312Do not write the username, password, cookie, Authorization header, request body, or connection string into artifacts, logs, command transcripts, screenshots, or generated scripts. Do not place credential literals in shell commands or reusable scripts. Prefer credentials already available through a local secrets/env file, environment variables, or the active browser login path.313314If credentials are present only in the active conversation/session and no non-recording shell injection path exists, do not give up immediately. First use the in-app browser or Chrome login form when available, because typing into the authorized login page does not require putting the secret in a shell transcript. After browser login succeeds, retry `.tp` and `.xml` from the authenticated browser/session. If browser automation cannot submit the login safely, ask the user to log in manually or provide a safe credential injection method. Only then mark `RUNTIME_LOGIN_SAFE_INJECTION_REQUIRED`, `XML_RAW_EXPORT_NOT_SAVED`, `RUNTIME_XML_EXPORT_AUTH_BLOCKED`, or a similar residual.315316Even when credentials cannot be submitted, parse the unauthenticated login HTML when available and record sanitized login mechanics: form action resolved URL, method, field names, HTTP status, and whether a `SESSION` cookie was issued. Do not record field values.317318Never treat text copied from Chromium's XML viewer as raw XML unless it round-trips through an XML parser. The viewer can decode escaped markup inside attributes, for example `valor="<div ...>"` becoming `valor="<div ...>"`, which makes the saved text invalid XML. If a browser-derived file fails XML parsing, classify it as `RUNTIME_XML_BROWSER_TEXT_INVALID`, keep it only as diagnostic evidence, and rely on a raw response body, authenticated HTTP export, local XML, or HADES/Cronos source for structural discovery.319320Only classify `.tp` or `.xml` as a non-blocking Phase 0 residual after one of these is true: authenticated login succeeded and the route/export still failed; browser login was impossible for a documented reason; or the user did not provide usable credentials. If credentials are available but login was not attempted, keep Phase 0 `Open` or `Blocked` with `RUNTIME_LOGIN_NOT_ATTEMPTED`; do not close it as `Ready for next phase with adjustments`.321322Phase 0 must not perform technical XML discovery. It may record that a local XML/export/database source candidate exists and, when cheap, confirm screen code/title. It must not extract or promote grid SQL, filters, binds, links, components, `dataTable`, write routes, Oracle objects, or field lineage; those belong to Phase 1. The Phase 0 readiness matrix lists only backend/API modules and libraries needed for Java/Spring APIs.323324Scaffold or factory scripts are convenience helpers only. Do not depend on them as the source of truth for Phase 0. If a scaffold/factory is missing, broken, or points to an absent template, continue by creating `migration-plan.md` and `phase-0-execution-gate.md` from the canonical repository templates, and record a non-business tooling residual such as `SCAFFOLD_UNAVAILABLE` with path, impact, and next action. A missing scaffold must not silently relax Phase 0 evidence requirements, must not justify skipping Oracle/XML/browser checks, and must not be recorded as a blocker for the business migration unless no canonical templates are available.325326## Ordered Phases3273281. **Phase 0 - Operational Preparation**329 - Define the screen/functionality to investigate, target backend/API module candidates, environment, repository access, database access, XML/debug source, legacy app/browser access, credentials availability, and initial expected user operations using the Standard Legacy Operation Inventory.330 - For Cronos/Archon screens, require a runtime XML export decision before Phase 1: `.tp` reachability, matching `.xml` export/download result, credential/session status, export permission status, parser-valid saved XML status, local XML path candidate, and whether the source-of-truth check is `ready`, `blocked`, or `deferred`.331 - If legacy credentials are available in the active session, attempt browser/app login before deciding `.tp` or `.xml` status. Reopen `.tp` and retry `.xml` after login. When the login page exposes a login form, resolve its real action URL and try the same flow with an in-memory HTTP session to persist the raw XML export. An unauthenticated `401`/`403` alone is not enough to defer authenticated runtime capture.332 - Test Oracle/banco with a simple read-only probe when credentials are available. Record the environment, success/failure, and whether Phase 1 can run Oracle/HADES checks.333 - Treat local XML as a source candidate only in Phase 0. Do not parse component lineage, grid SQL, filters, links, write `dataTable`, hidden fields, or route semantics in this phase.334 - Record only backend/API repositories and shared libraries required for Java/Spring API migration. Do not include visual/UI libraries as Phase 0 dependencies.335 - Do not store credentials in artifacts. Phase 0 may state that credentials are available for the active session, unavailable, invalid, or insufficient for XML export, but must not record usernames/passwords/secrets.336 - If credentials or authenticated runtime access are unavailable, close Phase 0 only with an explicit `RUNTIME_AUTH_BLOCKED` or `RUNTIME_XML_EXPORT_AUTH_BLOCKED` residual carried into Phase 1.337 - Treat scope as provisional in this phase. The real migration scope is closed in Phase 1 after observed legacy evidence.338 - Output: `migration-plan.md`.339 - Closeout: `phase-0-execution-gate.md`.3403412. **Phase 1 - Legacy Screen Operation Inventory**342 - Use `ergon-archon-screen-discovery`.343 - Close browser/XML/runtime SQL, component lineage, read data sources, keys, authorization, session context, visible actions, related links, and write surface discovery for every standard operation.344 - When a local legacy XML exists, require an explicit source-of-truth artifact before closing Phase 1: produce `cronos-source-of-truth.md` comparing local XML evidence against authenticated runtime/debug evidence and HADES/Oracle registry or stored-resource candidates. For Cronos/ErgonNG, treat XML as import/export for database-persisted page structure; check transaction, controls, properties, screen pattern/customization tables, and user screen pattern before accepting the local XML. Keep local XML at `CONFIRMED_LOCAL_SOURCE` until runtime/HADES equivalence is proven. If HADES/Oracle is unavailable, the artifact must exist with a `Blocked` or `Partial` decision and the exact rerun command/query.345 - For Cronos bind semantics, do not block only on Chrome/browser automation when XML plus Oracle metadata can answer the question. If `sqlParameters`, the SQL predicate, a reused component or equivalent screen, and Oracle metadata/view source close the value semantics, record the bind as `BIND_SEMANTICS_CLOSED_BY_XML_ORACLE` and classify it as public filter, server-side scope, constant bind, parent-row context, or internal runtime parameter. Use `docs/migracao/phase1-cronos-bind-resolution-standard.md` when present. For standard Cronos `recordPanelEdit + dataTable`, XML plus local Cronos framework source may close create/update payload as `SOURCE_DERIVED_PAYLOAD_READY_FOR_DB_PROBE`; browser/runtime remains mandatory for visible workflow, action state, restricted users, final parity, and non-standard write actions whose payload is not source-derived.346 - If the browser workflow is not fully operated by Codex, require `runtime-capture-form.md` so the developer has a structured way to provide the missing visible/runtime facts. `browser-runtime.md` alone is not enough when it only infers behavior from XML. For process validation before developer handoff, an unoperated or partial visual workflow blocks Phase 1 readiness; do not close Phase 1 as `Ready for next phase` or `Ready for next phase with adjustments` while default load, runtime binds, selected-row/public-key proof, visible action state, and representative non-empty fixture/context are missing.347 - When the workspace provides `docs/migracao/phase1-scope-authorization-standard.md`, apply it before Phase 1 handoff. `allowed-default-context` may close from authenticated browser default load, non-empty fixture, selected-row public key, 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 evidence shows a bypass of `HadesLegacyAccessGuard`/equivalent, `ErgonLegacyExecutor`/equivalent, public exposure of company/user/profile/security context, or custom security outside HADES. When the factory provides `new-phase1-scope-authorization-decision-pack.ps1`, generate the decision pack only for genuinely open scope/authorization cases; it structures owner approval/blocker evidence but does not make the gate Ready by itself. Do not expose company/user/profile/session context as public FilterDTO, schema, URL, option payload, or x-ui fields.348 - Require HADES registry/access/stored-resource coverage before Phase 1 can close. This can be executed evidence or an explicit blocked SQL/helper artifact, but a gate with `HADES_REGISTRY_NOT_CHECKED` must not advance to Phase 1.5.349 - `operation-inventory.md` must use deterministic states (`Implemented`, `Ready`, `Candidate`, `Blocked`, `Deferred`, `Not present`) instead of generic `Unknown`.350 - Output: `investigation.md`, `component-lineage-matrix.md`, `browser-runtime.md`, `runtime-capture-form.md` when needed, `cronos-source-of-truth.md`, `legacy-doc-351352…(truncated)