meta upgrade rewrites nothing on a YAML estate, then reports 'no retired vocabulary found' and exits 1

[dmealing]

Found while evaluating 0.24.0-rc.7 in an adopter project.

Summary

meta upgrade exists to rewrite the vocabulary retired in 0.24.0. On an estate whose
metadata is authored in YAML, it rewrites nothing — it skips every file and then reports
that it found nothing to do.

YAML is a first-class authoring format: metaobjects-authoring covers "YAML or canonical
JSON", and the scaffolded projects in question are YAML throughout. So for these adopters the
migration tooling for a breaking change is a no-op, and the entire migration is manual.

Observed

A 161-file YAML estate, run at the project root:

$ meta upgrade
meta: 161 YAML file(s) cannot be rewritten automatically and were NOT checked — migrate them by hand:
  <…all 161 listed…>
meta upgrade — no retired vocabulary found in the JSON metadata.
$ echo $?
1

The estate demonstrably does carry retired vocabulary — counted directly in those same YAML
files:

retired construct	occurrences
violation: (→ counterexample:)	321
status: abandoned / status: superseded	61
supersededBy:	22
verifiedBy:	1

All 405 are invisible to the tool.

Two things worth separating

1. The coverage gap. The mechanical half of this migration is exactly what a rewriter
should own. violation: → counterexample: alone is 321 identical single-token edits with no
judgement in any of them — precisely the work the command advertises ("rewrites retired
metadata vocabulary… retirements needing a human decision are REFUSED and listed"). Splitting
the estate by serialization means the adopters who need it most get none of it.

2. The report is actively misleading. The final line is
no retired vocabulary found in the JSON metadata. Read on its own — and it is the last line,
so it is the one that sticks — it says the estate is clean. The truth is the opposite: 405
retired constructs, none examined. The skip notice does appear first, but it is the header of
a 161-line file list, so on any real estate it has scrolled well off screen by the time the
conclusion prints.

Compounding it, the command exits 1. An adopter wiring meta upgrade into a script gets a
failure exit alongside a "nothing found" message, with no way to distinguish "nothing to do"
from "could not look".

Suggested fix

Ideally teach the rewriter YAML — the retirements at issue are key renames and key deletions,
which round-trip through a YAML parser as readily as JSON.

Failing that, at minimum:

• Make the conclusion reflect the skip: no retired vocabulary found in the 0 JSON file(s) checked; 161 YAML file(s) skipped — never a bare "not found" when nothing was examined.
• Reserve exit 1 for a real failure, or document what it means here; "I could not check
  anything" and "I checked and it is clean" must not share an exit code.
• Consider a scan-only mode that reports retired vocabulary in YAML even when it cannot
  rewrite it. Adopters could then at least size the migration and locate the sites, which is
  most of the value.

Workaround for adopters today

Do the rewrite yourself. The mechanical parts are a safe pass over the YAML — rename the
violation: key, delete the supersededBy: / verifiedBy: lines — and only the retired
@status values need a real decision per entry. Verified on the estate above: after that
pass, meta verify on 0.24.0-rc.7 loads all 321 requirement entries and reports zero
ERR_REQUIREMENT_*.

Related

#337 covers the load failure this migration exists to resolve.