summaryrefslogtreecommitdiff
path: root/plugins/code-modernization/commands/modernize-transform.md
diff options
context:
space:
mode:
Diffstat (limited to 'plugins/code-modernization/commands/modernize-transform.md')
-rw-r--r--plugins/code-modernization/commands/modernize-transform.md212
1 files changed, 99 insertions, 113 deletions
diff --git a/plugins/code-modernization/commands/modernize-transform.md b/plugins/code-modernization/commands/modernize-transform.md
index d946b93f..d3a1fb69 100644
--- a/plugins/code-modernization/commands/modernize-transform.md
+++ b/plugins/code-modernization/commands/modernize-transform.md
@@ -1,123 +1,109 @@
---
-description: Transform one legacy module to the target stack — idiomatic rewrite with behavior-equivalence tests
-argument-hint: <system-dir> <module> <target-stack>
+description: Rewrite one legacy module in the target stack, with tests that prove it behaves the same
+argument-hint: <system> [module] [target-stack]
+arguments: system module target_stack
---
-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.
-
-Read the source module and any business rules in `analysis/$1/BUSINESS_RULES.md`
-that reference it. Then present the plan and **stop — write no code until
-the user explicitly approves** (use plan mode if the session supports it):
-- Which source files are in scope
-- The target module structure (packages/classes/files you'll create)
-- Which business rules / behaviors this module implements
-- How you'll prove equivalence (test strategy)
-- Anything ambiguous that needs a human decision NOW
-
-Wait for approval before writing any code.
-
-## Step 1 — Characterization tests FIRST
-
-Before writing target code, spawn the **test-engineer** subagent:
-
-"Write characterization tests for legacy/$1 module $2. Read the source,
-identify every observable behavior, and encode each as a test case with
-concrete input → expected output pairs derived from the legacy logic.
-Target framework: <appropriate for $3>. Write to
-`modernized/$1/$2/src/test/`. These tests define 'done' — the new code
-must pass all of them. Follow your secret-handling rules: no credential
-literal from legacy code becomes a fixture; substitute fake same-shape
-values and read anything genuinely live from environment variables."
-
-Show the user the test file. Get a 👍 before proceeding.
+Transform module **`$module`** of `$system` into **$target_stack**, with proof of behavioral
+equivalence. This is one vertical slice of the strangler fig; output goes to
+`modernized/$system/$module/`.
+
+The code is `legacy/$system`, often a symlink to where it really lives: say where it points (`readlink legacy/$system`) in one line before you start. If `legacy/$system` does not exist, stop and say so: nothing can run without the code, so the fix is `/code-modernization:modernize $system --source <path to the code>`. Run every subagent in the foreground and wait for its result: never end your turn while one is still running. Stop any server or other process you started (a legacy app on a local port, a watcher) before you finish, and say you did. **If `$module` or `$target_stack` is empty**, read
+`analysis/$system/MODERNIZATION_BRIEF.md`: take the target stack it names, and the first module of
+the earliest phase whose `Command:` is `transform` that has no
+`modernized/$system/<module>/TRANSFORMATION_NOTES.md` yet (with no brief, the target in `INTENT.md`). Say which you picked.
+
+## Step 0 — Toolchain, then the plan (human gate)
+
+**Target stack (required).** The runtime, package manager and test framework must respond
+(`java -version` and `mvn -v`, `node -v` and `npm -v`, `python3 -V` and `pytest --version`). If not,
+stop and say what to install: a plan gate now would only defer the failure an hour. Point to
+`/code-modernization:modernize-preflight $system $target_stack`.
+
+**Legacy stack (advisory, never a blocker).** Try a syntax-only compile of the module. Legacy code
+often cannot build locally by nature (CICS and IMS programs have no local translator; the real runtime
+is a mainframe you do not have). If it cannot, dual execution is off the table: the tests assert
+against **recorded traces and golden-master fixtures** (real production outputs, captured reports,
+SME-confirmed examples). Say so in the plan and in `TRANSFORMATION_NOTES.md` ("equivalence is
+trace-based; legacy was not executable here"), so reviewers know how strong the proof is.
+
+**Run the old system only where it is safe.** Record baselines from the legacy code running on this
+machine, or against a test environment the person named. Never call a production or third-party
+service, register an account, or send or change real data to record a baseline unless the person
+approved that exact target in the plan (say which calls, and which of them write). A token, password
+or session cookie in a recorded response is a secret: replace it with a fixed fake value before
+anything is saved, and never print it.
+
+**The brief is binding.** If `MODERNIZATION_BRIEF.md` exists, find the phase whose `Command:` is this
+one and whose `Modules:` include `$module`, and treat its scope, entry criteria, exit criteria and any
+edits the user made as binding. An unmet entry criterion is the next step: meet it, never re-plan
+around it. If no phase covers `$module`, stop and ask which phase this is.
+
+Read the module's source and the rules in `BUSINESS_RULES.md` that reference it, and any verdicts on them in `analysis/$system/RULE_REVIEWS.json`: a rule marked `wrong` is not pinned as the oracle (use the reviewer's note for what is right, and if the note does not say, ask), and a P0 rule marked `discuss` is a question to settle at this plan gate before any code. Then present the
+plan and **stop: write no code until the user explicitly approves** (plan mode if available): which
+source files are in scope, the target structure, which rules and behaviors it implements, how you will
+prove equivalence, and anything ambiguous that needs a human decision now.
+
+## Step 1 — Characterization tests first
+
+Spawn the **test-engineer** subagent: "Write characterization tests for module $module of legacy/$system.
+Read the source, identify every observable behavior and encode each as a test with concrete input and
+expected output derived from the legacy logic. Target framework: <right for $target_stack>. Write to
+`modernized/$system/$module/src/test/`. These tests define 'done'. Name the `RULE-NNN` id(s) each test pins
+(from `analysis/$system/BUSINESS_RULES.md`) in its name or a one-line comment, so the trace can find it. Follow your secret-handling rules:
+no credential from legacy code becomes a fixture; use fake same-shape values and read anything live
+from environment variables." Show the user the test file and get a yes before going on.
## Step 2 — Idiomatic transformation
-Write the target implementation in `modernized/$1/$2/src/main/`.
-
-**Critical:** Write code a senior $3 engineer would write from the
-*specification*, not from the legacy structure. Do NOT mirror COBOL paragraphs
-as methods, do NOT preserve legacy variable names like `WS-TEMP-AMT-X`.
-Use the target language's idioms: records/dataclasses, streams, dependency
-injection, proper error types, etc.
-
-Include: domain model, service logic, API surface (REST controller or
-equivalent), and configuration. Add concise Javadoc/docstrings linking each
-class back to the rule IDs it implements.
-
-## Step 3 — Prove it
-
-Run the characterization tests:
-```bash
-cd modernized/$1/$2 && <appropriate test command for $3>
-```
-Show the output. If anything fails, fix and re-run until green.
-
-## Step 4 — Side-by-side review
-
-Generate `modernized/$1/$2/TRANSFORMATION_NOTES.md`:
-- Mapping table: legacy file:lines → target file:lines, per behavior
-- Deliberate deviations from legacy behavior (with rationale)
-- What was NOT migrated (dead code, unreachable branches) and why
-- Follow-ups for the next module that depends on this one
-
-Then show a visual diff of one representative behavior, legacy vs modern:
-```bash
-delta --side-by-side <(sed -n '<lines>p' legacy/$1/<file>) modernized/$1/$2/src/main/<file>
-```
-(Fall back to `diff -y --width=160` if `delta` isn't installed.) Never
-pick a credential-bearing line range for this diff, and mask any
-credential-like literal quoted in TRANSFORMATION_NOTES.md — the notes
-live in `modernized/` and get committed.
+Write the implementation in `modernized/$system/$module/src/main/`. **Write what a senior
+$target_stack engineer would write from the *specification*, not from the legacy structure:** do not
+mirror COBOL paragraphs as methods or keep names like `WS-TEMP-AMT-X`; use the target's idioms
+(records, streams, injection, proper error types). Include the domain model, service logic, API
+surface and configuration, and link each class to the rule IDs it implements in a short comment.
+
+## Step 3 — Prove it, and prove the proof can fail
+
+While iterating, run only this module's tests; run the whole suite once before Step 4.
+
+1. **Run the tests** (`cd modernized/$system/$module` and the stack's test command) and show the
+ output. Fix and rerun until green.
+2. **Count what ran.** Report `equivalence cases executed: N`. A run that executed **zero** cases proved
+ nothing, and a comparison test must **fail, never skip,** when its legacy oracle or fixture is
+ missing: a suite that is green because everything skipped is not green. If the oracle was
+ unreachable, fix that; do not report the suite as passing.
+3. **Show the tests can fail.** Temporarily break the new code in one small way that matters (change a
+ rounding mode, shift a threshold by one, flip a comparison), confirm at least one test goes red,
+ restore it, and record `Canary: <the change> → <N> tests failed` in the notes. If nothing failed,
+ the tests do not pin the behavior: strengthen them before going on.
+4. **When the legacy code can run here**, also run both systems on the same inputs, save each output
+ under `analysis/$system/equivalence/legacy/` and `.../new/`, list the pairs in
+ `analysis/$system/equivalence/cases.json` (paths relative to that folder; the schema is at the top of
+ `scripts/compare.py`), and run
+ `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/compare.py" analysis/$system/equivalence/cases.json --out analysis/$system/EQUIVALENCE.json`.
+ That script, not your judgment, decides same or different. Mask only fields that legitimately vary
+ (timestamps, generated ids) and say what each mask hides. A difference you accept is recorded with a
+ reason in the case's `approvedDifference`, and only a person accepts it.
+ Floating-point numbers that another compiler or math library prints slightly differently are not a
+ mask: give that case a `tolerance` (`rel` or `abs`, and a `why`), which compares numbers written with a
+ decimal point or exponent within it, every other byte exactly, and is listed in the result.
+
+## Step 4 — Notes and a side-by-side
+
+Write `modernized/$system/$module/TRANSFORMATION_NOTES.md`: a mapping table (legacy file:lines to target
+file:lines, per behavior); deliberate deviations with rationale; what was NOT migrated (dead code,
+unreachable branches) and why; the canary result and the executed-case count; follow-ups for the next
+dependent module. Show one representative behavior side by side
+(`diff -y --width=160 <(sed -n '<lines>p' <legacy file>) <target file>`). Never pick a credential-bearing
+range, and mask any credential-like literal in the notes: they live in `modernized/` and get committed.
+This is your own evidence: `/code-modernization:modernize-verify $system $module` is the independent re-check
+(it re-runs the tests and the comparison, tries new inputs, and gives one verdict).
## Step 5 — Architecture review
-Spawn the **architecture-critic** subagent to review the transformed code
-against $3 best practices. Apply any HIGH-severity feedback; list the rest
-in TRANSFORMATION_NOTES.md.
+Spawn the **architecture-critic** subagent to review the code against $target_stack best practice.
+Apply HIGH-severity feedback and list the rest in the notes.
-Report: tests passing, lines of legacy retired, location of artifacts.
+Report: tests passing, cases executed, lines of legacy retired, where the artifacts are. Refresh the
+report (`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_report.py" $system`, a convenience: if it fails or `python3` is missing, say so in one line and carry on). The next step is the brief's next module, or `/code-modernization:modernize-harden $system`
+when the phase is done.