docs(qa): rewrite the cli.migrate-meta-codemod P1 to what os migrate meta actually does

[os-zhuang]

Fixes #9733

docs/qa/platform-checklist/areas/cli.json carried cli.migrate-meta-codemod as an
active P1 asserting that os migrate meta rewrites authored sources. It does not,
and the item's own grep step targeted a sentence that #9529 withdrew — so the item could
not be run at all, and a runner taking it at face value would have filed a P1 failure
against a capability that was never built.

Disposition: rewrite to today's contract, keep it active and P1

This follows the triage ruling on the issue (2026-08-18, Option B). Weighed against the
alternatives:

• Retire / park it on feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591 — cheapest, and wrong. Six of the item's assertions hold
  today (printed edit list, untouched sources, schema-valid snapshot, idempotent replay,
  floor refusal, semantic advisories, --json exit honesty). The item could not pass
  because of a wording defect in the item, not because coverage was missing; retiring
  it would have taken real P1 coverage to zero to fix a sentence.
• Split — a second parked item for the codemod half would duplicate feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591, which
  already carries the capability with its own Restart-when: line.
• Rewrite (taken) — drop only the false assertion, keep everything real, and put the
  restart condition inside the item so feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591's landing is detected rather than hoped
  for.

What happens when #9591 lands in v18

The restart is mechanical, not a note someone has to remember. The item's last step and
last acceptance clause read the --help flag surface and pin today's exact flag list;
a --write (or equivalent) appearing there is defined in the clause as the signal to
restore the removed assertions and bump the revision — explicitly not a failure. A
knownGaps entry states the same in the other direction, so a runner does not record the
missing rewrite as blocked(dependency) or file it as a defect. #9591 stays the home of
the capability; this item stays the thing that notices it arrived.

The capability claim, verified here rather than inherited

packages/cli/src/commands/migrate/meta.ts declares exactly:

from · to · step · out · stored · database-url · apply · yes · force · type · json

A probe for in-place rewrite flag names (write|fix|in-place|inPlace|rewrite|codemod)
against that declaration block returns zero hits, exit 1. The same probe shape run as
a positive control over out|apply|stored|from returns four hits at lines 195/208/212/222,
so the zero is a real absence and not a broken probe.

Both writeFileSync calls on the authored-source arm are --out-guarded
(if (flags.out) writeFileSync(resolve(flags.out), JSON.stringify(result.stack, null, 2))),
and the command's own header states the position:

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

#9591 (open, pm:on-hold, target:v18) proposes --write as the flag that does not exist yet.

Residue sweep, re-derived on this branch

Sweeping for the withdrawn sentence to rewrite existing sources automatically finds six
files: this checklist item (the only live assertion), the deliberate pin fixture
packages/spec/src/shared/retired-key-migrate-sentence.test.ts, and four CHANGELOG.md
histories. Only the checklist item is touched here.

Sweeping for the replacement house sentence finds 50 files — 30 .ts plus 20
.mdx docs pages. The 30 .ts figure matches the pre-dispatch measurement; the 20
.mdx are additional surface that sweep did not cover, and are consistent with it rather
than in conflict.

After this change cli.json still matches a grep for the withdrawn sentence, deliberately:
the revision-3 history entry quotes it verbatim to record what was removed, in the same
past-tense register as the CHANGELOGs. That is outside the class pin's reach — its corpora
are packages/spec/src and packages/lint/src only — so it cannot turn that pin red.

Verification

pnpm check:platform-checklist is not a CI gate. .github/workflows/lint.yml
records the maintainer decision that it runs on a manual cadence, and
scripts/pm/dispatch-gates.mjs independently places 0 of 117 check families on this
path. So the local run below is the only run this change gets, which is why it carries a
reverse verification rather than resting on CI.

Run at 9725a1267, exit codes captured before any pipe:

node scripts/checklist-select.mjs --self-test        EXIT=0
  -> checklist-select self-test: 17 cases pass.

node scripts/check-platform-checklist.mjs            EXIT=0
  -> check-platform-checklist: OK - 15 areas, 204 items (204 active);
     coverage: 30 kinds mapped, 0 waived.

node scripts/check-nul-bytes.mjs                     EXIT=0
  -> check-nul-bytes: OK (scanned 6122 text file(s) ... no raw ASCII control bytes).

204 items, 204 active — unchanged, confirming the P1 was rewritten and not quietly dropped.

Reverse verification (predicted direction: red). Stripping the oracle key from the
new restart clause, confirmed on disk by re-parsing the file and printing the clause's
remaining keys (['clause', 'verify', 'evidence'], oracle present: False):

node scripts/check-platform-checklist.mjs            EXIT=1
  -> cli.json - cli.migrate-meta-codemod: acceptance[7] "oracle" must be
     one of api|network|screenshot|dom|log|test|build

It names acceptance[7] — the clause this PR adds — so the green above is reading the new
content, not skipping it. The restore leg was then run and re-confirmed on disk (oracle: log
present again, working tree clean against HEAD) with the validator back to EXIT=0. No build
or dist/ is involved: the validator imports only node builtins plus a sibling .mjs, so it
was run outside the shared verify lock, declared.

Clause ②: not triggered. The path limb is packages/spec/src/** and this touches none of
it; on content, a QA ledger document changes no contract accept/reject behaviour and widens no
public surface.

Changeset: none owed — the diff is one file under docs/qa/** and reaches no published
packages/*, so the PR carries skip-changeset.

Scope

One file, one item. Two adjacent findings were filed unassigned rather than fixed here; they
are named in the report on #9733. Neither #9591 nor #9529 is addressed by this PR — #9591
remains open as the v18 capability.

---

Generated by Claude Code