feat(cli): meta upgrade — rewrite retired vocabulary, refuse what needs a decision

Plan: docs/superpowers/plans/2026-08-21-meta-upgrade-vocabulary-rewriter.md. Wires the
rewriter into the CLI. Previews by default; `--apply` writes; `--to <version>` bounds which
retirements apply.

DELIBERATELY NOT `meta migrate`. That command owns DATABASE SCHEMA (ADR-0015) and an adopter
reading `migrate` expects DDL. Overloading the most destructive command in the toolchain so
it sometimes edits metadata instead would make "what does this touch?" ambiguous at exactly
the wrong moment.

It resolves the file set through `resolveCollection` — the single authority on where metadata
lives, so `sources` is honoured — and hands each file's RAW TEXT to the rewriter. It never
loads: the metadata this exists to repair is metadata that does not load.

EXITS NON-ZERO WHILE ANY REFUSAL STANDS, even when every mechanical change succeeded. A
refusal means the metadata still will not load, so exiting 0 would let CI record the
migration as complete while the build is broken. Pinned by a test.

DOGFOODING FOUND A REAL BUG THE UNIT TESTS COULD NOT. Run against
`error-requirement-verified-by-retired` — a fixture that genuinely fails to load today —
the rewriter emitted INVALID JSON: dropping `@verifiedBy` when it is the LAST key in its
object left the preceding key's comma dangling (`"...",\n}`). Every drop test I had written
placed the retired attr in the middle, where a trailing comma is always there to consume, so
all of them passed against a document that no longer parsed.

Two fixes, one mechanical and one about the tests:
  - when there is no trailing comma the key is last, so the PRECEDING comma is taken instead
  - every drop case now asserts `JSON.parse` succeeds. Substring assertions were all TRUE of
    the broken output — that is precisely how it got through, and the same shape as the
    vacuous fixture caught earlier today.

A tool whose whole job is producing loadable metadata cannot emit invalid JSON, and it would
have shipped had I trusted a green suite over running it on real data.

Also verified against the shipped `examples/advanced-modeling` project: exit 0, "no retired
vocabulary found", nothing touched.

The help snapshot gains exactly one line (the new command); reviewed the diff rather than
blanket-accepting it.

Verified: metadata 2465 pass / 0 fail, cli 615 / 0 fail, typecheck clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/cli/src/commands/upgrade.ts

@@ -0,0 +1,161 @@
+// server/typescript/packages/cli/src/commands/upgrade.ts
+//
+// `meta upgrade` — rewrite retired vocabulary in this project's metadata.
+//
+// DELIBERATELY NOT `meta migrate`. That command owns DATABASE SCHEMA (ADR-0015) and an
+// adopter reading `migrate` expects DDL. Overloading it with a metadata rewrite would make
+// the most destructive command in the toolchain ambiguous about what it touches.
+//
+// IT DOES NOT LOAD THE METADATA, and cannot. Once vocabulary is deregistered, metadata
+// carrying it fails the load — which is exactly the state this command exists to repair. So
+// it resolves the file SET through `resolveCollection` (the single authority on where
+// metadata lives) and hands each file's RAW TEXT to the rewriter. See
+// `metadata/src/vocabulary-rewrite.ts` for why that is the only workable shape.
+//
+// DRY-RUN BY DEFAULT, per this repo's convention for anything that edits committed files.
+// `--apply` writes. Refusals exit NON-ZERO even when every mechanical change succeeded, so
+// CI cannot mistake a partial upgrade for a finished one.
+
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { resolveCollection } from "@metaobjectsdev/sdk";
+import { rewriteDocument, type RewriteResult } from "@metaobjectsdev/metadata";
+import { log } from "../lib/log.js";
+
+interface UpgradeFlags {
+  apply: boolean;
+  maxVersion?: string;
+  projectRoot?: string;
+}
+
+function parseArgs(argv: string[]): UpgradeFlags {
+  const flags: UpgradeFlags = { apply: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] as string;
+    if (a === "--apply") flags.apply = true;
+    else if (a === "--to") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error("--to needs a version");
+      flags.maxVersion = v;
+    } else if (a.startsWith("--to=")) flags.maxVersion = a.slice("--to=".length);
+    else if (a === "--help" || a === "-h") throw new Error("__help__");
+    else if (!a.startsWith("-")) flags.projectRoot = a;
+    else throw new Error(`unknown option: ${a}`);
+  }
+  return flags;
+}
+
+/**
+ * The node type a document's keys belong to.
+ *
+ * Retirements are TYPE-SCOPED — `@unique` is retired on `identity.secondary` and live on a
+ * field — so the rewriter needs a scope per occurrence, not per file. A metadata file holds
+ * many types, so we run the rewriter once per type key present in the text. Cheap, and it
+ * keeps the scoping decision in one place (the map) rather than smeared across a parser we
+ * deliberately do not have.
+ */
+function typeKeysIn(text: string): string[] {
+  const keys = new Set<string>();
+  const re = /"([a-z]+)\.([A-Za-z*]+)"\s*:/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) keys.add(`${m[1]}.${m[2]}`);
+  return [...keys];
+}
+
+/** Run every type scope present in the document, threading the text through each pass. */
+function rewriteAllScopes(text: string, maxVersion: string | undefined): RewriteResult {
+  const changes: RewriteResult["changes"][number][] = [];
+  const refusals: RewriteResult["refusals"][number][] = [];
+  let current = text;
+  for (const typeKeyHint of typeKeysIn(text)) {
+    const r = rewriteDocument(current, {
+      typeKeyHint,
+      ...(maxVersion !== undefined ? { maxVersion } : {}),
+    });
+    current = r.text;
+    changes.push(...r.changes);
+    refusals.push(...r.refusals);
+  }
+  return { text: current, changes, refusals };
+}
+
+export async function upgradeCommand(args: string[], cwd: string): Promise<number> {
+  let flags: UpgradeFlags;
+  try {
+    flags = parseArgs(args);
+  } catch (err) {
+    if ((err as Error).message === "__help__") {
+      log.info(
+        "meta upgrade [<project>] [--to <version>] [--apply]\n\n" +
+          "  Rewrites retired metadata vocabulary. Previews by default; --apply writes.\n" +
+          "  Retirements needing a human decision are REFUSED and listed with their guide.",
+      );
+      return 0;
+    }
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  const projectRoot = flags.projectRoot ?? cwd;
+
+  let files: readonly string[];
+  try {
+    files = (await resolveCollection(projectRoot)).files;
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+
+  let totalChanges = 0;
+  let totalRefusals = 0;
+  let filesChanged = 0;
+
+  for (const file of files) {
+    const before = await readFile(file, "utf8");
+    const r = rewriteAllScopes(before, flags.maxVersion);
+    if (r.changes.length === 0 && r.refusals.length === 0) continue;
+
+    const rel = relative(projectRoot, file);
+    log.info(`\n${rel}`);
+    for (const c of r.changes) log.info(`  ${c.line}: @${c.from} → ${c.to}`);
+    for (const f of r.refusals) {
+      log.warn(
+        `  ${f.line}: @${f.attr}${f.value !== undefined ? `: ${f.value}` : ""} — needs a decision. ` +
+          `Retired in ${f.since}. ${f.migration !== undefined ? `See ${f.migration}` : f.why}`,
+      );
+    }
+
+    totalChanges += r.changes.length;
+    totalRefusals += r.refusals.length;
+    if (r.changes.length > 0) {
+      filesChanged++;
+      if (flags.apply) await writeFile(file, r.text, "utf8");
+    }
+  }
+
+  log.info("");
+  if (totalChanges === 0 && totalRefusals === 0) {
+    log.info("meta upgrade — no retired vocabulary found.");
+    return 0;
+  }
+
+  if (flags.apply) {
+    log.info(`meta upgrade — rewrote ${totalChanges} declaration(s) across ${filesChanged} file(s).`);
+  } else {
+    log.info(
+      `meta upgrade — ${totalChanges} declaration(s) in ${filesChanged} file(s) can be rewritten. ` +
+        `Re-run with --apply to write.`,
+    );
+  }
+
+  // Non-zero while ANY refusal stands, applied or not. A partial upgrade that exited 0 would
+  // let CI record the migration as done while metadata still fails to load.
+  if (totalRefusals > 0) {
+    log.error(
+      `${totalRefusals} declaration(s) need a human decision and were left untouched — ` +
+        `see the guides listed above.`,
+    );
+    return 1;
+  }
+  return 0;
+}

server/typescript/packages/cli/src/index.ts

@@ -23,6 +23,7 @@ COMMANDS:
   export                Flatten loaded metadata to one canonical JSON artifact
   docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
+  upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
@@ -377,6 +378,10 @@ export async function run(argv: string[]): Promise<number> {
       const { verifyCommand } = await import("./commands/verify.js");
       return verifyCommand(rest, cwd);
     }
+    case "upgrade": {
+      const { upgradeCommand } = await import("./commands/upgrade.js");
+      return upgradeCommand(rest, cwd);
+    }
     case "prompt-snapshot": {
       const { promptSnapshotCommand } = await import("./commands/prompt-snapshot.js");
       return promptSnapshotCommand(rest, cwd);

server/typescript/packages/cli/test/__snapshots__/cli.test.ts.snap

@@ -16,6 +16,7 @@ COMMANDS:
   export                Flatten loaded metadata to one canonical JSON artifact
   docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
+  upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version

server/typescript/packages/cli/test/upgrade-command.test.ts

@@ -0,0 +1,118 @@
+// `meta upgrade` end-to-end, against real files on disk.
+//
+// The unit tests prove the rewriter transforms text. These prove the COMMAND does the right
+// thing to a project: previews without writing, writes only under --apply, and — the one
+// that matters for CI — exits NON-ZERO while any refusal stands, so a partial upgrade
+// cannot be recorded as a finished one.
+
+import { describe, test, expect, afterAll } from "bun:test";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { upgradeCommand } from "../src/commands/upgrade.js";
+
+const dirs: string[] = [];
+afterAll(async () => {
+  for (const d of dirs) await rm(d, { recursive: true, force: true });
+});
+
+async function project(meta: string): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "meta-upgrade-"));
+  dirs.push(root);
+  await mkdir(join(root, "metaobjects"), { recursive: true });
+  await writeFile(join(root, "metaobjects", "meta.json"), meta, "utf8");
+  return root;
+}
+
+const WITH_RETIRED = `{
+  "metadata.root": {
+    "package": "acme::shop",
+    "children": [
+      { "requirement.functional": {
+          "name": "orderRecord",
+          "@level": 4,
+          "@status": "live",
+          "@statement": "An order records what was bought",
+          "@violation": "An order that cannot say what was bought",
+          "@verifiedBy": ["OrderServiceTest"]
+      }}
+    ]
+  }
+}`;
+
+const NEEDS_DECISION = `{
+  "metadata.root": {
+    "package": "acme::shop",
+    "children": [
+      { "requirement.functional": {
+          "name": "oldThing",
+          "@level": 4,
+          "@status": "abandoned",
+          "@statement": "Something we stopped doing",
+          "@violation": "n/a"
+      }}
+    ]
+  }
+}`;
+
+const CLEAN = `{
+  "metadata.root": {
+    "package": "acme::shop",
+    "children": [
+      { "requirement.functional": {
+          "name": "orderRecord",
+          "@level": 4,
+          "@status": "live",
+          "@statement": "An order records what was bought",
+          "@violation": "An order that cannot say what was bought"
+      }}
+    ]
+  }
+}`;
+
+describe("meta upgrade", () => {
+  test("PREVIEWS without writing by default", async () => {
+    const root = await project(WITH_RETIRED);
+    const code = await upgradeCommand([root], root);
+    expect(code).toBe(0);
+    // Untouched on disk — the default must never edit committed files.
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toBe(WITH_RETIRED);
+  });
+
+  test("--apply rewrites the file", async () => {
+    const root = await project(WITH_RETIRED);
+    expect(await upgradeCommand([root, "--apply"], root)).toBe(0);
+    const after = await readFile(join(root, "metaobjects", "meta.json"), "utf8");
+    expect(after).not.toContain("@verifiedBy");
+    // Everything else survives, byte-for-byte in the untouched regions.
+    expect(after).toContain('"@statement": "An order records what was bought"');
+    expect(after).toContain('"name": "orderRecord"');
+  });
+
+  test("a project with nothing retired exits 0 and is untouched", async () => {
+    const root = await project(CLEAN);
+    expect(await upgradeCommand([root, "--apply"], root)).toBe(0);
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toBe(CLEAN);
+  });
+
+  // The CI-facing contract. A refusal means the metadata still will not load, so exiting 0
+  // would let a pipeline record the migration as complete while the build is broken.
+  test("EXITS NON-ZERO when a decision is still required", async () => {
+    const root = await project(NEEDS_DECISION);
+    expect(await upgradeCommand([root, "--apply"], root)).toBe(1);
+    // And leaves the judgment case alone rather than guessing.
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toContain('"abandoned"');
+  });
+
+  test("--to bounds which retirements apply", async () => {
+    const root = await project(WITH_RETIRED);
+    // @verifiedBy retired in 0.24.0, so a 0.23.0 ceiling must leave it alone.
+    expect(await upgradeCommand([root, "--to", "0.23.0", "--apply"], root)).toBe(0);
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toContain("@verifiedBy");
+  });
+
+  test("rejects an unknown flag with exit 2", async () => {
+    const root = await project(CLEAN);
+    expect(await upgradeCommand([root, "--nope"], root)).toBe(2);
+  });
+});

server/typescript/packages/metadata/src/vocabulary-rewrite.ts

@@ -222,15 +222,29 @@ export function rewriteDocument(source: string, opts: RewriteOpts): RewriteResul
         changes.push({ attr, from: attr, to: rw.to, line });
       } else if (rw.kind === "dropAttr") {
         if (span === undefined) continue;
-        // Take the trailing comma and the line's own whitespace with it, so removing a
-        // middle key does not leave a dangling `,` or a blank line behind.
+        // Take the TRAILING comma and the line's own whitespace, so removing a middle key
+        // leaves neither a dangling `,` nor a blank line.
         let end = span.end;
         while (end < source.length && /[ \t]/.test(source[end] ?? "")) end++;
-        if (source[end] === ",") end++;
+        const hadTrailingComma = source[end] === ",";
+        if (hadTrailingComma) end++;
+
         let start = keyStart;
         while (start > 0 && /[ \t]/.test(source[start - 1] ?? "")) start--;
+
+        // THE LAST-KEY CASE, found by dogfooding rather than by the unit tests above: when
+        // the retired attr is last in its object there IS no trailing comma — the comma
+        // belongs to the PRECEDING key. Dropping without taking it leaves `"...",\n}`,
+        // which does not parse. A tool whose whole job is producing loadable metadata
+        // cannot emit invalid JSON.
+        if (!hadTrailingComma) {
+          let back = start;
+          while (back > 0 && /[\s]/.test(source[back - 1] ?? "")) back--;
+          if (source[back - 1] === ",") start = back - 1;
+        }
+
         if (source[start - 1] === "\n" && source[end] === "\n") end++;
-        else if (start > 0 && source[start - 1] !== "\n") start = keyStart;
+        else if (start > 0 && source[start - 1] !== "\n" && hadTrailingComma) start = keyStart;
         edits.push({ start, end, text: "" });
         changes.push({ attr, from: attr, to: "(removed)", line });
       } else {

server/typescript/packages/metadata/test/vocabulary-rewrite.test.ts

@@ -33,6 +33,10 @@ describe("mechanical rewrites", () => {
     expect(r.text).toContain('"@level": 4');
     expect(r.changes).toHaveLength(1);
     expect(r.changes[0]?.attr).toBe("verifiedBy");
+    // Substring assertions alone are what let the trailing-comma bug through — they were
+    // all true of a document that no longer parsed. Every drop case now proves the result
+    // is still valid JSON.
+    expect(() => JSON.parse(r.text)).not.toThrow();
   });
 
   test("rewrites key AND value for @readOnly", () => {
@@ -73,6 +77,34 @@ describe("surgical editing", () => {
     expect(r.text.indexOf('"@statement"')).toBeLessThan(r.text.indexOf('"@level"'));
   });
 
+  // Caught by dogfooding against a real fixture, not by the tests above — the drop cases
+  // there all had a following key, so the trailing comma was always there to consume. When
+  // the retired attr is LAST, the comma belongs to the PRECEDING key and dropping naively
+  // leaves `"...",\n}` — invalid JSON, from a tool whose entire job is producing loadable
+  // metadata.
+  test("dropping the LAST key does not leave a trailing comma", () => {
+    const src = `{
+  "requirement.architectural": {
+    "name": "MoneyIsExactMinorUnits",
+    "@statement": "Amounts are exact integer minor units",
+    "@verifiedBy": ["MoneyRoundingTest"]
+  }
+}`;
+    const r = rewriteDocument(src, { typeKeyHint: "requirement.architectural" });
+    expect(r.text).not.toContain("@verifiedBy");
+    // The real assertion: the result must still parse.
+    expect(() => JSON.parse(r.text)).not.toThrow();
+    expect(JSON.parse(r.text)["requirement.architectural"]["@statement"]).toBe(
+      "Amounts are exact integer minor units",
+    );
+  });
+
+  test("dropping the ONLY key leaves a valid empty object", () => {
+    const src = `{ "requirement.functional": { "@verifiedBy": ["T"] } }`;
+    const r = rewriteDocument(src, { typeKeyHint: "requirement.functional" });
+    expect(() => JSON.parse(r.text)).not.toThrow();
+  });
+
   test("a document with nothing to change comes back BYTE-IDENTICAL", () => {
     const src = `{
   "requirement.functional": {