The Migration Story

The lesson most foundations courses skip

Nobody starts from greenfield. Somewhere in your estate is the old system — at Meridian (as in the reference estate), a legacy Jenkins whose every job routes through one opaque shared-library wrapper: all logic coupled to controller plugins and self-hosted agents, understood by one person who left. The migration off it is where this training’s patterns prove they compose — and where the industry’s dirtiest secret about migrations gets taught: the pipeline migration is the easy half.

The easy half, pattern by pattern

The reference migration’s target shape maps one-to-one onto this course:

FROM Jenkins opaque wrapper            TO multi-stage YAML where...
one controller-global shared library -> versioned template repos consumed
  (invisible logic, all-or-nothing      by PINNED @alias refs (2.2/2.3:
  upgrades)                             deliberate upgrades, visible logic)
scattered post-hoc scan jobs         -> SAST/SCA as STAGE ONE - the gate
                                        leads the pipeline (3.4's severity
                                        wiring)
rebuild-per-environment              -> artifact hash generated at build,
                                        RE-VERIFIED before every environment
                                        deploy (5.1's house standard)
"deploy" = a job someone runs        -> environment-gated deploy stages with
                                        health checks (2.1's approvals,
                                        4.3's gates)

Sequencing rule: migrate onto the governed patterns, never onto blank YAML — a migration that hand-translates each Jenkins job into bespoke pipeline files replaces one ungoverned estate with another that’s merely newer. Each moved service consumes the starter (which is why 6.1’s paved road precedes this lesson: the migration is the paved road’s biggest customer). And run the old and new in parallel per service until the hard half below signs off — the Jenkins job’s last run is a decommission-register event (retire-with-dates, as always), not a vibe.

The hard half: behavioral parity

Here’s what the reference migration’s transcripts teach that no tooling vendor will: with the new pipeline green, artifacts hashed, and gates gating, the team then spent the real effort proving the migrated application behaves identically — and the numbers are the lesson: 601 routes compared between old and new deployments; ~84% verified equivalent by automated comparison; and a stubborn remainder that could not be verified by simple probing — session-dependent flows and legacy frameset routes that answer only to a real, stateful browser session. Plus one gotcha for the ages: a timestamp discrepancy that turned out to be an environment timezone difference (EST on the old host, GMT on the new) masquerading as an application bug.

The generalized discipline — parity as a first-class migration phase:

1. INVENTORY the behavior surface (routes, jobs, outputs), not just the code
2. COMPARE mechanically where probes suffice - and record coverage honestly
   (84% is a number you report, not round up)
3. ESCALATE the unprobeable remainder to the right instrument - stateful
   browser tests (4.1's framework exists for exactly this), not more curl
4. EXPECT environment deltas (timezones, locales, default encodings) and
   diff the ENVIRONMENTS, not just the responses
5. DONE means: parity coverage reported, remainder dispositioned, old
   system's retirement DATED - "the pipeline is green" appears nowhere
   in this list

If the shape feels familiar, it should — it’s Cloud Modernization’s characterization-testing discipline applied at the platform seam. Different migration, same law: behavior preservation is the contract; the pipeline is merely the vehicle.

Closing the training: name the gaps, schedule the re-checks

The reference estate — whose patterns filled this course — also models the last discipline by omission: for all its supply-chain rigor, its corpus never names the frameworks it substantially practices (5.3’s naming exercise exists because of exactly this), its scanning defaults tell a wart-story (3.4), and its docs lied about its branching until audited (1.2). A foundations program is never finished; it is operated: the doc-vs-reality audit quarterly, the version matrix on its bump cadence, the exception registers expiring, the metrics read monthly, the volatile facts (this training flagged its own throughout) re-verified on schedule. That operating rhythm — not any single pattern — is what you’re actually taking from this course.

Your turn, one last time: run Lesson 1.1’s capability self-assessment on your own team, pick the one capability the evidence says to fix first, and take its module of this training to your next sprint — with the AI CLI doing the heavy lifting and the measurement lesson keeping everyone honest.

Key takeaway

Migrate onto the governed patterns — pinned templates, gate-first stages, hashed artifacts, environment gates — one service at a time onto the paved road; then do the hard half: behavioral parity with honest coverage, the right instruments for the unprobeable remainder, environment diffs for the sneaky deltas, and retirement dates gated on evidence. The pipeline being green begins the ending; parity ends it. And the training ends where operating begins: audit, measure, expire, re-verify — with your AI CLI carrying the toil and the measurements keeping the vibes honest.