modernize-transform

Transform legacy/$1 module $2 into $3, with proof of behavioral equivalence.

This is a surgical, single-module transformation — one vertical slice of the strangler fig. Output goes to modernized/$1/$2/.

Step 0a — Toolchain check (fail fast on target, adapt on legacy)

Verify the build environment before planning, not when the tests first run:

• Target stack ($3) — required. Runtime, package manager, and test framework all respond (java -version + mvn -v, node -v + npm -v, python3 -V + pytest --version, …). If any are missing, stop and report what to install — the new code and its tests cannot run without them, so a plan gate now would just defer the failure an hour. Suggest /modernize-preflight $1 $3 for the full readiness report.
• Legacy stack — advisory, never a blocker. Try a syntax-only compile of the module being transformed (e.g. cobc -fsyntax-only). Legacy code often cannot build locally by nature, not by misconfiguration — CICS/IMS programs have no local translator, and the real runtime may be a mainframe you don't have. A failed or impossible legacy compile does not stop the transform; it changes the equivalence strategy:
  • dual-execution proof is off the table — characterization tests assert against recorded traces / golden-master fixtures (real production outputs, captured reports/screens, SME-confirmed examples) instead of live legacy runs
  • say so explicitly in the Step 0b plan and later in TRANSFORMATION_NOTES.md ("equivalence is trace-based; legacy was not executable in this environment"), so reviewers know the strength of the proof they're approving

Step 0b — Plan (HITL gate)

The brief is binding — read it first. If analysis/$1/MODERNIZATION_BRIEF.md exists, this transform is one phase (or one module of a phase) of that plan: read it before deciding anything below. Find the phase that names this command with $2 in scope, and treat that phase's scope, entry criteria, exit criteria, and any edits the user made to it as binding on the plan you present below. Entry criteria are gates, not context: if one is not met (a prior phase's exit criteria, an SME sign-off the brief requires), meeting it is the next step — do not proceed past it and do not silently re-plan around it. If the brief exists but no phase covers $2, stop and ask which phase this is. The user steers execution by editing the brief; a brief the execution command never reads cannot steer anything.