MajorTom

A major-version dependency upgrade is one of the most feared tasks in software maintenance, and the reason is not the size of the diff — it is that **the diff looks right and the software is still broken.** Express 5 is a concrete case. `app.del()` was removed. `res.send(status)` was removed. `res.send(body, status)` was removed. Wildcard routes must be named. Optional route parameters must be rewritten with braces. Regex-style paths no longer compile. A developer who searches for each removed symbol finds them all, edits them mechanically, and ships — then discovers at runtime that `/:format?` became required, that `/*` throws at registration, and that the route table silently matches nothing. Existing tools do not solve this. Documentation says what changed, not which lines in *this* repository are affected. Search-and-replace finds tokens without knowing whether an occurrence is a call, a comment, a string, or a same-named variable. An LLM asked to "upgrade this project" produces a plausible diff, cites nothing, and cannot say which of its changes were guesses. Manual review catches mistakes only after they are written. **Our solution.** MajorTom is a CLI-first agent that performs the migration from the vendor's own guide and refuses to claim success it cannot prove. It takes four inputs — a repository, one dependency, a target version, and that dependency's official guide as PDF, Markdown, or URL — then runs seven ledgered stages. **PLAN** turns the guide into a structured plan where every item carries a verbatim quote. **IMPACT** scans the repository and partitions affected files into disjoint queues. **BASELINE** captures a pre-edit test result; with no tests the run is fatal, because nothing can be claimed without them. **EXECUTE** applies edits through a filesystem facade that physically confines each worker to its own queue, validates every result by parsing it, rolls back failures, then bumps the manifest and reinstalls. **VERIFY** re-runs the suite and classifies each failure. **REPORT** emits a Markdown report tracing every change to its justifying guide section. Three invariants make the output trustworthy. **I1:** work happens on `majortom/<runId>`; `main` and `master` are refused and no force-push or merge path exists. **I2:** an edit is applied only when a plan item authorises it, and citation coverage is computed from real edit records, never declared by the caller. **I3:** the guide is treated strictly as data — instructions found inside a migration document are ignored, so a malicious or confused document cannot redirect the tool. **Target users** are teams on frameworks and libraries — the engineers who own upgrades and currently dread them, and the security teams waiting on the CVE fix behind one. **What makes it creative** is the trust mechanism. Citation coverage is a computed number, not a promise: an edit with no guide quote behind it is refused and flagged `HUMAN REVIEW` rather than applied. The property that distinguishes it is **honest accounting**. A test that failed before the migration is recorded and excluded; a test that fails because of the migration is reported as such; and when the run is not green, MajorTom says NOT GREEN and exits non-zero. A passing run and a failing run are equally easy to produce, because the tool has no incentive to prefer either. **Efficiency, measured on a real run:** Express 4.21.2 → 5.1.0, nine files changed, 16 of 16 applied edits cited (100% coverage), 19.5 seconds wall clock, one pre-existing failure correctly excluded. The project ships 138 tests and `npm audit --omit=dev` reports zero vulnerabilities.