# Ergon Migration Orchestration

> 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.

- Skill: `codexrodrigues/ergon-migration-orchestration` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add codexrodrigues/ergon-migration-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/ergon-migration-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/ergon-migration-orchestration

---


# 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:

```bash
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:

1. Locate the latest `docs/migracao/<SCREEN>/phase-<PHASE-ID>-execution-gate.md`.
2. Confirm its state is `Ready for next phase` or `Ready for next phase with adjustments`.
3. Read the gate's `Continuacao Curta` or next-step section as the source of truth.
4. 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.
5. Carry residuals from the gate into the new phase.
6. 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:

1. request the `.tp` route and retain the `SESSION` cookie only in memory;
2. submit credentials to the resolved form action with the form field names observed in the HTML, commonly `username` and `password`;
3. request the matching `.xml` route with the same in-memory session;
4. 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="&lt;div ...&gt;"` 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

1. **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`.

2. **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)
