modernize-uplift

Uplift legacy/$1 from $2 to $3 — same stack, newer version.

This is not /modernize-transform. There you extract intent and rewrite idiomatically. Here the code is good; it just needs to run on a newer runtime. You preserve structure and make the smallest diffs that compile and behave identically on the target, driven by the known breaking changes between $2 and $3 — not by re-deriving the business logic.

The potential advantage of a same-stack uplift: if both runtimes execute in this environment, the same test suite can run on both and your equivalence proof becomes a real differential test (run on both, diff the results). That is the strong case — but it is not always available, and the command is explicit about when it is:

• It depends on the stack. .NET can multi-target one test project to both framework monikers (<TargetFrameworks>net48;net8.0</TargetFrameworks>), but net48 only executes on Windows/Mono — on a Linux/macOS box or most CI sandboxes the old leg cannot run. Java 8→17 is not one suite over two targets at all — it is the whole build run twice under two JDK toolchains. Python 2→3 cannot import the same un-rewritten module under both interpreters. So "true dual-run" is the best case, common only for .NET-on-Windows.
• When both runtimes are not runnable here, equivalence degrades — exactly like /modernize-transform — to characterization tests pinned to recorded/expected outputs on the target only. That is fine; it just must be labelled honestly (Step 0.3, Step 7).

Optional 4th arg $4 scopes to projects/modules matching a pattern.

Step 0 — Toolchain & version pinning (fail fast)

1. Pin the version pair precisely. "$2 → $3". If either is vague (e.g. ".NET" with no number), stop and ask — the entire delta catalog depends on the exact pair.
2. Target runtime — required for dual-run. Verify the target toolchain builds and tests (dotnet --version + dotnet test smoke; mvn/gradle; python3 -V + pytest).
3. Source runtime — required for the baseline oracle. A same-stack uplift's strength is that the old version also runs locally. Verify it. If the source runtime is NOT available here (common in CI/sandboxes — e.g. no .NET Framework on Linux), say so explicitly: dual-run degrades to target-only, and equivalence falls back to characterization tests pinned to recorded/expected outputs (as in /modernize-transform). Note this in the plan and UPLIFT_NOTES — reviewers must know whether the proof was a true dual-run or target-only.
4. Test framework on the target — the one question that reshapes the plan. Answer, before any planning: can the existing test suite execute on $3 as-is? The test framework is a dependency like any other, and one whose runner/adapter does not support the target runtime is the single most common reason an uplift's phase order comes out wrong: the test migration is then a prerequisite, not a leaf, because nothing you migrate can be validated until the tests that validate it run on $3. Read the framework and version out of the test manifests and check it against $3 — NUnit 2 or MSTest v1 cannot execute on modern .NET, JUnit 4 needs the vintage engine on newer platforms, nose/unittest2 do not run on Python 3, and so on for whatever this stack's test manifests declare. If the answer is no, say so now: it becomes an explicit early phase in the plan (Step 2) and in /modernize-brief, never a trailing one.
5. Detect the ecosystem migration tool — and distinguish present / runnable-here / actually-ran. Most of these tools need a working restore + build (and often network), which a read-only sandbox does not have, so "installed" ≠ "produced findings". Report all three states and never fold a tool's findings into the catalog unless it actually ran — say "coverage lost: needs restore+network, unavailable here" instead.
   • .NET: dotnet upgrade-assistant (loads + restores the project; also applies changes in place — see Step 5). The legacy Portability Analyzer (apiport) analyzes compiled assemblies, not source, and is Windows-centric/archived — treat as optional, not primary.
   • Java/Spring: OpenRewrite (mvn rewrite:dryRun is genuinely headless and emits a patch — the most reliable of these; lean on it).
   • Python: pyupgrade (source-level, runnable). Note 2to3 is deprecated and removed in Python 3.13; python-modernize is abandoned — don't rely on them.
   • JS/Angular: ng update (edits in place, needs a clean git tree + node_modules; no real report-only mode).