CHANGELOG-MIGRATION.md: no recipes for 2.0.0-3.1.0; following the file as written destroys content 5.0.0 says to keep

[CodingEbert]

Summary

CHANGELOG-MIGRATION.md ships recipes for 3 versions (v1.10.0, v4.0.0, v5.0.0), but CHANGELOG.md lists 16 releases between 1.9.0 and 5.0.0. Everything from 2.0.0 through 3.1.0 has no recipe.

This is not just a docs gap. The file's own instructions, followed literally on a 1.x folder, lead an LLM to delete member content that v5.0.0 explicitly says to preserve.

The contradiction

CHANGELOG-MIGRATION.md opens with:

This file is machine-actionable. An LLM reading only this file should be able to migrate any older myPKA scaffold folder to the latest version deterministically.

To migrate, find the highest version newer than <root>/.scaffold-version, then apply each version's recipe in order from oldest to newest.

If .scaffold-version is missing, assume v1.x and apply every recipe from v1.10.0 onward.

An LLM doing exactly that on a 1.x folder hits v2.0.0, which has no recipe — so it falls back to CHANGELOG.md, where [2.0.0] says:

Breaking structural change. The base scaffold roster moves from nine specialists to six. […] Updating from 1.10.x to 2.0.0 is breaking — the base roster shrinks by three.

It deletes Iris, Charta, Pixel, GL-003-design-system, and SOP-007–SOP-010. It then continues to v5.0.0, whose recipe says:

Migration recipe: NONE REQUIRED

There is nothing to run. Do not delete anything from an existing folder.
[…] the scaffold updater never removes an installed pack.

The member has now lost three agents, a Guideline, and four SOPs that the target version says to keep. The intermediate step destroyed data the endpoint would have preserved.

manifest.json already encodes the correct behavior — its changes.paths block has 10 entries, all change_type: "changed", zero removed. The data says "delete nothing." Only the migration prose says otherwise.

Dangling forward-reference

CHANGELOG-MIGRATION.md line 80, inside the v4.0.0 recipe's Step 1/8:

• If the version is 3.1.0 (or below 4.0.0 and at/above 3.1.0), continue. (If it is below 3.1.0, apply the earlier recipes in order first, then return here.)

There are no earlier recipes between 1.10.0 and 4.0.0. Any folder below 3.1.0 — i.e. every 1.x and 2.x folder — is told to apply recipes that do not exist. The recipe chain terminates.

Also unrecipe'd in the gap

• 2.2.0 adds GL-004-task-resource-linking. A member who authored their own GL-004 gets a number collision with no guidance. It also says a pre-GL-004 linked_tasks field is "retired — remove it on touch."
• 2.3.0 makes Goal key_element required — this edits PKM/, which manifest.json declares sacred under user_state_paths. A migration step and the manifest disagree about whether PKM may be written.
• 2.4.0 says "If you upgrade an existing clone, refresh your local .gitignore from this release" — a security-relevant step (the hardened ignore covers .env, keys, *.db) with no recipe and no validation.

Impact

A 1.x member cannot follow the documented upgrade path to completion. The outcomes are:

1. Stall at the dangling reference, or
2. Improvise the missing steps from CHANGELOG.md and destroy content 5.0.0 says to keep.

Outcome 2 is the dangerous one, and it is what the file's own instructions steer toward. The only thing standing between a member and silent data loss is the note at the bottom of the file ("Never invent steps not in the recipe […] surface it as a question") — which directly contradicts the header's claim that an LLM reading only this file can migrate "deterministically."

Suggested fix

Migration here should converge to the target, not replay history. myPKA is additive by design and 5.0.0 treats installed packs as user-state, so the intermediate roster churn (9 → 6 in 2.0.0, packs bundled in 3.0.0, unbundled in 5.0.0) is irrelevant to someone landing on 5.0.0 today. Replaying it is not just wasted work, it is lossy.

Concretely, in rough priority order:

1. Add a direct 1.x → 5.0.0 bridge recipe — the additive union (tasks/journals from 1.10.0, the update core from 4.0.0, version mirrors), skipping the intermediate removals entirely.
2. Fix line 80's dangling reference.
3. State explicitly that 2.x/3.x recipes are intentionally absent, and that v2.0.0's removals are superseded by v5.0.0's "do not delete anything."
4. Reconcile 2.3.0 with the manifest on whether a migration may write to PKM/.
5. Reconcile the header's "deterministic" claim with the closing "never invent steps" rule — as written they cannot both hold.

Context

Found while bridging a real 1.9.0 folder (heavily customized: 18 specialists, local GL-003/GL-004, local SOPs) to 5.0.0. I stopped and did not apply the 2.x removals, on the strength of v5.0.0's "do not delete anything" plus the all-changed/zero-removed manifest. The additive parts of the 1.10.0 and 4.0.0 recipes applied cleanly and the folder validates. But that required reading all three files and reasoning about the conflict — which is exactly what a machine-actionable spec is supposed to make unnecessary.

Related: #22 (validation-script.sh model-id false positive), found in the same pass.