COBOL modernization with golden files and Droids

Most COBOL modernization failures are behavioral. A program that compiles in Java can still round a currency amount differently, truncate a field the old program padded, or write records in a different order. Factory's approach to COBOL modernization keeps a deterministic check at every step. A compiler validates each edit, a parser builds the inventory, and golden files recorded from real batch inputs decide whether migrated code matches the original. Droids do the work between those checks.

The same estate rarely contains only COBOL. Mainframe applications mix COBOL and PL/I programs, JCL that defines batch job steps and datasets, copybooks shared across hundreds of programs, CICS transactions, Db2 access through embedded SQL, and VSAM files. Each of these needs a tool that reads it the way the mainframe does.

Why COBOL needs deterministic evidence

COBOL encodes much of its behavior in data definitions. A PIC S9(7)V99 COMP-3 field is a signed packed-decimal number with two implied decimal places. A MOVE into a shorter numeric field silently truncates high-order digits unless the program checks for size errors. Arithmetic follows the ROUNDED clause or truncates. None of that is visible in a casual reading of the procedure division, and a translation that maps such a field to a Java double changes results.

Approving a migration therefore needs evidence beyond a code read, whether a person or an agent does the reading.

The evidence has to come from running both versions on the same input and comparing the output. Droids are useful for producing that evidence quickly, because they can read copybooks, write the harness, and investigate each difference. The verdict itself comes from the comparison.

Build the inventory with a compiler and a parser

Start by getting the current source to compile outside the mainframe. The GnuCOBOL compiler, cobc, accepts dialect options including -std=ibm for IBM compatibility and -std=mf for Micro Focus compatibility. The -fsyntax-only flag checks syntax without generating code, -I adds a copybook directory to the search path, and -E preprocesses only. In that mode the compiler executes directives, removes comment lines, and expands COPY statements into a .i file. Expanded sources are what a reviewer and a Droid should read, because they show the record layouts each program actually uses.

Programs with EXEC CICS or EXEC SQL blocks need a precompiler or stubs before a non-mainframe compiler can process them. Record which programs fall into that group, because they will need a different translation and test strategy.

PL/I programs need the same treatment with different tools. GnuCOBOL does not compile PL/I, so syntax checks for those programs come from the vendor compiler or from the analysis stage of a translation service. A Droid can still read PL/I source, summarize what each procedure does, and map its record layouts, and golden files apply to PL/I batch jobs exactly as they do to COBOL.

A parser gives the inventory structure. The ProLeap COBOL parser is an ANTLR4-based Java library that produces an abstract syntax tree and an abstract semantic graph with data and control flow information. Its documentation states that it passes the NIST test suite and that it extracts EXEC SQL and EXEC CICS statements as text. A small program built on it can list every paragraph, every CALL target, every file a program opens, and every copybook field it reads or writes.

A Droid writes that inventory program, runs it, and turns the output into a dependency map. The JCL completes the picture, because each job step's DD statements name the datasets a program reads and writes. Those datasets are the inputs and outputs that golden files will capture.

Capture golden files before changing anything

A golden file is the output the current system produces from a recorded input. Michael Feathers calls this kind of check a characterization test in Working Effectively with Legacy Code. It records what the system does today, correct or not, so a changed system can be held to it.

For a batch program, capture the input datasets and the output datasets for a representative set of runs. Include month-end and year-end runs, empty inputs, and records that exercise error paths. Mask or synthesize personal data according to policy before the files leave the production boundary.

Comparison must be record by record and field by field. Decode packed-decimal fields to their numeric value, convert text with the same EBCDIC code page the mainframe uses, and compare every field defined in the copybook layout. A byte-level diff on raw files catches differences but explains none of them. A field-level comparison names the record, the field, and both values. A Droid can generate the comparison harness from the copybook, and an engineer reviews it once. After that it runs unchanged on every migrated program.

Some differences will be intentional. A migration may fix a known defect or change a date format that a downstream system no longer needs. Record each approved difference with its reason and the person who approved it, and encode it in the harness as an explicit exception. The golden file itself stays unchanged.

For regulated environments, the data boundary shapes the whole setup. Legacy modernization with private AI agents covers keeping source, inference, and validation inside approved infrastructure.

Choose a translation path

Teams usually pick between two paths, and many use both for different parts of the estate.

Replatform. The COBOL stays COBOL and runs on a different runtime, such as GnuCOBOL or a commercial COBOL environment. The work is dialect differences, file handling, JCL replacement with scripts or a scheduler, and the precompiled CICS and SQL programs. Golden files show whether the recompiled programs behave identically.

Refactor. The COBOL is translated into another language, usually Java. AWS Transform for mainframe supports z/OS applications written in COBOL and PL/I with associated JCL, CICS transactions, BMS screens, Db2 databases, and VSAM files, and refactors COBOL workloads into Java. AWS has also changed the older service. Its availability notice states that the AWS Mainframe Modernization self-managed and Managed Runtime Environment experiences are no longer open to new customers, with new work directed to AWS Transform and vendor-direct offerings. Check the current status of any vendor tool before planning around it.

Whichever tool translates the code, it leaves residue. Generated Java may not compile against the target framework version, a utility program may have no mapping, and some programs will fail a golden-file comparison on a rounding rule or a sort order. Droids work through that residue one failing program at a time, and each fix is judged by the same comparison. Once the Java compiles and matches, the Java ecosystem's own deterministic tools take over, as described in Java modernization with OpenRewrite.

How Factory runs the COBOL loop

Factory runs the same loop for COBOL as for other languages, with the compiler and golden files as the gates.

Compile on every edit. A PostToolUse hook runs after each file edit. This script syntax-checks an edited COBOL program against the copybook directory. When cobc fails, the script exits with code 2, and the compiler's messages go back to the Droid.

#!/usr/bin/env bash
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.cbl|*.cob) ;;
  *) exit 0 ;;
esac
if ! out=$(cobc -fsyntax-only -std=ibm -I "$FACTORY_PROJECT_DIR/copybooks" "$file" 2>&1); then
  echo "$out" >&2
  exit 2
fi

Write the procedure down once. A skill holds the migration playbook, including the dialect flags, the comparison harness command, the rule that tool output and agent fixes go in separate commits, and the rule that a golden file is never edited to make a test pass.

Run one program at a time. Droid Exec runs headless, so a script can take the list of programs that fail comparison, run one droid exec --auto low per program, and rerun the comparison afterward. Programs that still differ are reported for a person to examine.

Plan the estate as milestones. For a full application, Missions plan the work as features and milestones, with validation at the end of each milestone. A natural first milestone is the inventory and golden-file capture, before any program changes.

These commands cover the deterministic steps a Droid runs in this loop.

Frequently asked questions

Can Factory translate COBOL to Java by itself?

Factory does not ship a COBOL transpiler. Droids work alongside deterministic tools such as the GnuCOBOL compiler, parser-based inventories, and translation services, then fix residue, write comparison harnesses, and explain programs. Golden-file comparisons decide whether a translated program is correct.

What is a golden file in COBOL modernization?

A golden file is the output a batch program produced from a recorded input on the current system. The migrated program runs on the same input, and a record-by-record comparison must find no differences, or each difference must be explained and approved.

Why expand copybooks before analysis?

Copybooks hold record layouts and shared code that programs include with COPY statements. Running cobc -E executes compiler directives and expands COPY statements, so analysis and review work on the source the compiler actually sees.

Is AWS Mainframe Modernization still available?

As of November 2026, AWS states that the self-managed and Managed Runtime Environment experiences of AWS Mainframe Modernization are no longer open to new customers. Existing customers can continue, and AWS points new work toward AWS Transform and vendor-direct offerings.

Does COBOL modernization require sending code outside the company?

Not with Factory Private, which places the control plane in customer-owned infrastructure. Golden files built from production inputs should still be masked or synthesized according to the data policy before they enter any development environment.

Further reading

• Deterministic code modernization with Factory
• Enterprise software modernization beyond the demo
• How to run a runtime upgrade with coding agents
• Missions planning and validation