The scaffold's upgrade path — 2026-09-27

A design note from the engineering record. SPEC N42 is the row and D52 the decision.

The question

m0 new writes a project once, and nothing touches its files again. Taking a newer m0 moved the CLI and the framework's source, and left everything the scaffold wrote as the older m0 wrote it. Between m0 0.2.0 and 0.3.0, six of the ten files every template writes changed: AGENTS.md, deploy/Dockerfile, deploy/README.md, deploy/fly.toml, .gitignore and pyproject.toml. The Dockerfile is the one that bites. 0.3.0's installs libsqlite3-0 in the runtime stage and makes /app/data for a volume; 0.2.0's does neither, so an application that upgrades and adopts m0_sqlite builds an image that cannot open its library. Nothing said so.

The toolchain had a trap of its own. m0 refuses any mojo but the one it was gated on and names the fix, uv add --dev 'mojo==Y'. With max-core installed that command cannot resolve: max-core 26.6.0 and mojo 1.1.0 each require mojo-compiler==1.1.0 exactly (PyPI's metadata, read 2026-09-27), so moving mojo alone leaves two pins on two compilers.

What was built

The doctor names what an upgrade would change. m0 doctor compares the scaffold's own files with what the running m0 writes for the project's name, and names those that differ. The scaffold's own files are every one m0 new writes except the README and pyproject.toml, which are the application's from its first edit. It reports and never fails. A difference is the application's own edit as often as an older m0's file (unotes edited its Dockerfile, .dockerignore and fly.toml on its first deploy), and only the application can tell which. A file the application removed is not compared. The name comes from pyproject.toml, so a project moved to another directory still matches. The new m0 is the only thing that knows what changed, and the doctor is the command an upgrade already runs, because the toolchain refusal sends you there.

The toolchain moves in one command. With max-core installed, mojo-gated's fix names both pins: uv add --dev 'mojo==Y' 'max-core==Z'. Without it, the sentence is unchanged.

What was not built, and why

There is no m0 upgrade. Rewriting a file safely needs a three-way merge: what the old m0 wrote, what the application made of it, and what the new m0 writes. The first is recorded nowhere, and recording it now would help only projects written from now on. A rewrite without it either discards the application's edits or refuses whenever there are any, which is most deploys. The retiring condition is in D52.

No version stamp is written into the scaffold either. A stamp would make every upgrade report every file, whatever changed, which is the noise the content comparison avoids.