AI-Assisted Porting at Scale

Revisiting the port, honestly

Lesson 2.2 waved the port through in one line — “assume that work is done” — and moved on to packaging. This lesson is that omitted work — because in 2026 the port is where AI-assisted modernization either proves itself or quietly corrupts fifteen years of business rules. The method has three legs: a harness that defines correct, an agent that does the mechanical work, and gates where humans spend their attention where it counts.

Leg 1: characterization tests define “correct” before anything moves

AssetTrack has no test suite (Lesson 1.2, weakness #3). Before porting, you do not write the tests you wish it had — you write tests that pin down what it currently does, bugs and all:

Build a characterization harness for the nightly batch jobs. For each job:
- Run it against the golden input set (last quarter's real inputs, sanitized)
- Capture every output: files, DB writes, log lines with timestamps normalized
- Store as golden outputs. The assertion is byte-equivalence (or field-level
  equivalence where timestamps/sequence values legitimately differ - list each
  exception explicitly and why)
Do NOT fix anything you find. If a job rounds currency oddly, the golden
output preserves the odd rounding. Behavior preservation is the contract;
improving behavior is a separate, later decision.

That last instruction is the discipline that makes the whole method safe. A port that “fixes” behavior mid-flight has changed two things at once, and when the numbers differ you cannot say which change caused it. Port first, verify equivalence, then queue improvements as ordinary tracked work against a system you once again understand.

Leg 2: the agent executes, in task-pack units

Lesson 1.4’s atomic task packs were designed for this exact executor. The port decomposes into packs — one service, one namespace, one batch job at a time — each with declared file scope, its characterization tests named as the done-check, and dependencies ordered so parallel agents never collide:

Execute task pack P3-07: port the MeterReadingImport job to .NET 10.
Scope: src/Jobs/MeterReadingImport/** only. Out of scope: shared utilities
(P3-02, already merged), the scheduler wiring (P3-14, later).
Method: preserve behavior exactly. Where a Framework API has no direct .NET 10
equivalent, choose the closest match and RECORD the substitution in the pack's
notes - do not silently improvise.
Done: characterization suite for this job passes byte-equivalent; build clean;
no new warnings suppressed.

The recorded-substitution rule matters more than it looks: the API seams (AppDomain behavior, culture-sensitive string handling, binary serialization, System.Web remnants) are exactly where silent behavior drift hides. Forcing each substitution into the pack notes turns “mysterious rounding difference in October” into “P3-07 note 4, reviewed on merge.”

Leg 3: humans verify where verification pays

At agent speed, “a human reviews every line” is a pleasant fiction that decays into “a human scrolls every diff.” Spend attention deliberately instead:

The harness carries the equivalence burden precisely so human attention can concentrate on the three rows machines cannot judge: whether a substitution is semantically safe, whether an authorization path is intact, and whether the sampled work smells right.

Key takeaway

Characterization tests define correct before anything moves; agents execute the port in task packs that record every API substitution; and human review concentrates where machines cannot judge — substitutions, auth, money, and samples. Behavior preservation first, improvements after, and the calendar planned around the parts that did not compress.