docs(qa): cli.doctor-deprecation-scan no longer calls os migrate meta a codemod

[claude]

Fixes#10418

docs/qa/platform-checklist/areas/cli.json, item cli.doctor-deprecation-scan, described os migrate meta twice as a codemod. It is not one. Both descriptors now say what the command is, and name #9591 as the commissioned-but-unbuilt in-place codemod.

The two claims, before and after

1 — the EXPECTED-FAIL acceptance clause

• before: "The real metadata codemod is os migrate meta (cli.migrate-meta-codemod)."
• after: "The remediation path that DOES exist is os migrate meta (cli.migrate-meta-codemod) — but it is not a codemod: it replays the migration chain and PRINTS the mechanical edits for the author to apply by hand. It declares no --write/--fix/in-place flag (exactly from/to/step/out/stored/database-url/apply/yes/force/type/json, commands/migrate/meta.ts:195-239) and writes no source file — both writeFileSync calls are guarded by if (flags.out) (:347 and :394-396) and emit a JSON snapshot, and the header at :155-157 declines the AST rewrite as 'unsafe and lossy'. The in-place codemod is commissioned as feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591 (v18, pm:on-hold) and has not been built, so a hint rewritten to name os migrate meta must promise a LIST of edits, not an auto-fix."

2 — the source descriptor

• before: "sibling items cli.doctor-health-report (…) and cli.migrate-meta-codemod (the codemod that actually exists)"
• after: "… and cli.migrate-meta-codemod (os migrate meta — the remediation path that does exist; its revision 3 asserts the command LISTS mechanical edits and rewrites no source file. The id keeps its -codemod spelling only because ids are immutable and never reused (README lifecycle) — it reads as a forward reference to feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591, not as a description of today's command)"

A source entry for #9591 was added alongside it, so the clause's reference resolves to the card that owns the unbuilt capability.

What did NOT change: the item's load-bearing assertion. os doctor's remediation hint at doctor.ts:2149 still prescribes objectstack codemod v2-to-v3, registered nowhere in packages/cli/src/commands/, and the clause is still the expected-fail. The clause now also warns that a fix which merely repoints the hint at os migrate meta must describe it as a list, not an auto-fix — otherwise a dead prescription is replaced by a false one.

Facts re-derived at this base (f4e5d916d6)

fact	evidence
flag surface	packages/cli/src/commands/migrate/meta.ts:195-239 — from :195, to :199, step :203, out :208, stored :212, database-url :218, apply :222, yes :226, force :231, type :235, json :239. No --write/--fix/in-place: a grep -nE "write|fix|in-place|inplace" over the file returns only the writeFileSync import, prose in comments, and the --stored row-rewrite text.
the two guarded writes	:347if (flags.out) writeFileSync(resolve(flags.out), …) and :394-396if (flags.out) { writeFileSync(…); printInfo('Wrote migrated stack snapshot → …') } — the only writeFileSync call sites in the file.
header sentence	:155-157 — "The command does not silently rewrite TS config source (that AST rewrite is unsafe and lossy); --out writes the canonicalized stack as a JSON snapshot the agent can diff and adopt."
#9591	still open, labels enhancement · domain:cli · target:v18 · pm:on-hold; nothing in packages/cli implements it.

Revision protocol

revision 1 → 2 with a history entry, per docs/qa/platform-checklist/README.md ("Change — edit the fields, bump revision, append a history entry saying what changed and why. The revision matters because run records pin the revision they ran against"). The entry's shape is copied from the single-line sibling entry cli.scaffold-console-first-paint revision 2 ({ "revision", "date", "change", "ref" }, ref naming the card that commissioned the change, as cli.migrate-meta-codemod revision 3 does with #9733). The two old wordings survive inside that history entry only — quoted as what was corrected, which is what the README asks a history entry to record.

Verification

pnpm check:platform-checklist is two halves; both run separately with the exit code captured before any pipe, at final commit 862b32b7b8:

checklist-select --self-test = 0 ✓ checklist-select self-test: 17 cases pass.
check-platform-checklist = 0 OK — 15 areas, 205 items (205 active); coverage: 30 kinds mapped, 0 waived; traps: 19 documented, 19 in use
check:doc-authoring = 0 ✓ doc authoring guard: 389 files clean
check:doc-formula-expressions= 0 ✓ 22 record-scoped formula example(s) across 416 files / 1443 TS blocks judged clean
check:nul-bytes = 0 OK (scanned 6252 text file(s); no raw ASCII control bytes)

Both halves were also green before the edit (0 / 0), so the revision/history check is confirmed to have been satisfied on both sides rather than only after.

The last three families are what node scripts/pm/dispatch-gates.mjs names for this change set (docs/** ⇢ doc-authoring and doc-formula-expressions; nul-bytes for any edit). check:doc-formula-expressions needed pnpm --filter '@objectstack/lint^...' build first — before that it failed on a missing @objectstack/formula/dist, which reads exactly like a real red.

⚠️check:platform-checklist is NOT wired into CI — by maintainer decision (.github/workflows/lint.yml:954-960, and the same decision restated in the directory README). This local green is therefore the only signal this change will ever get; no CI job will re-run it on this PR. Do not read a green CI as covering the checklist.

No ablation applies: this is a prose correction with no guard under test — there is nothing whose deletion would flip a check from green to red, so the slot is empty rather than filled with a ceremonial run.

Out of scope, deliberately

• cli.migrate-meta-codemod — read, not touched. Its revision-3 text (QA checklist item cli.migrate-meta-codemod is active P1 for a capability that does not exist — it asserts os migrate meta rewrites authored sources #9733 / PR docs(qa): rewrite the cli.migrate-meta-codemod P1 to what os migrate meta actually does #10412, merged 2026-08-20) already states the print-only contract correctly and does not repeat the claim; its -codemod id is immutable by README lifecycle, and revision 3 already documents that as a forward reference.
• packages/cli/src/commands/migrate/meta.ts — the command is correct; the checklist was wrong.
• feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591 — not built, not scoped.
• scripts/check-platform-checklist.mjs — untouched; fix(qa-checklist): resolve provisioning.use against its own area's recipes (#10593 gap 1) #10810 is in flight against it and this change does not trip it.

Did the claim spread?

Checked, and reported on the issue: the word "codemod" is attached to os migrate metanowhere else. docs/qa/platform-checklist/FOLLOW-UPS.md:212 calls it "the real path" (accurate), content/docs/protocol/backward-compatibility.mdx:134 says only that an automated codemod command is not yet available, and the content/docs/releases/v17.mdx hits are a different, unrelated codemod script. A separate defect was found in the same class and filed rather than fixed here — four docs-site lines attribute an in-place rewrite to os migrate meta --from, which the same docs site contradicts in bold at content/docs/upgrading.mdx:145.

---

Generated by Claude Code