os doctor --scan-deprecations prescribes a codemod command that does not exist

[baozhoutao]

Found by QA run #10663 driving cli.doctor-deprecation-scan at framework 79ebb37. Also recorded in PR #10147 FOLLOW-UPS §7b; this card is its extraction with live confirmation.

Symptom

After reporting deprecated patterns, os doctor --scan-deprecations prints:

ℹ Found N deprecated pattern(s). Run `objectstack codemod v2-to-v3` to auto-fix.

(doctor.ts:2149). But no codemod command is registered: os codemod v2-to-v3 → exit 2 "command codemod:v2-to-v3 not found"; os codemod --help → exit 2 "Command codemod not found." The docs already admit it: content/docs/protocol/backward-compatibility.mdx:134 — "An automated codemod command is referenced in the migration guides but is not yet available." The real, registered metadata codemod is os migrate meta.

Suggested fix

Point the hint at a command os actually registers (os migrate meta), scope/remove it, or gate it behind the command's existence.

Passing clauses

The scanner itself works correctly: file:line attribution for all 8 DEPRECATED_PATTERNS (incl. the retired referenceFilters→lookupFilters pair), --verbose → replacement lines, warns-not-gates (exit 0 both with hits and clean), .test.ts / node_modules / .json decoys all skipped for their documented reasons, and absent-src/ honesty. The item is accurate on every checked particular (exit is oclif's 2, not 1, for the missing command — still nonzero).

QA-source: #10663 · cli.doctor-deprecation-scan · clause 6 (expected-fail probe)

[os-zhuang]

Triage: lands in packages/cli (doctor.ts:2149) ⇒ pm:queue · domain:cli · type Bug. Rationale: the tool prescribes a command that does not exist (objectstack codemod v2-to-v3); docs already admit it. Fix: point the hint at the registered os migrate meta, or gate/remove it — smallest honest change wins. Mechanical, S.

Serial constraint: #10679 also edits doctor.ts — fold-or-serial answered on that card: default serial, #10679 first, this card after (or one claim folding both with the five gates answered). Second-lander merges main before opening the PR.

Size/model suggestion: S, sonnet acceptable (mechanical string/gate fix judged by existing gates), opus if folded with #10679.

---

Generated by Claude Code

[os-elon]

Claim: domain:cli lane execution seat
Session: session_019bmVFqoQPq63zhKrxdYG1r
Branch: claude/issue-10680-doctor-codemod-hint
Worktree: objectstack-issue-10680
Domain: domain:cli
File surface: packages/cli/src/commands/doctor.ts — the codemod hint triage places at :2149 — plus its tests. ⛔ Re-derive the anchor at head; see the freshness warning below.
Container & model: S, mode:subagent, model: opus
Clause-②: no — this corrects a hint string the tool prints. No request is accepted or refused differently and nothing published widens.
Serial constraints cleared: the hold triage set is discharged. #10679 landed — verified in main by content (a7ea3289eb, doctor.ts carries the monorepo-only check skip), not from a merged flag. doctor.ts is free.

⚠️ doctor.ts changed today — branch from current main

#10799 rewrote a large part of this file hours ago (183 lines): findMissingTests / findDeprecatedUsages now return a MonorepoTreeScan, the ✓ print sites moved inside a scanned arm, and the Not built probe is gated. Every line number below the edits has shifted, including triage's :2149. ⛔ Do not trust that anchor, and do not work from a cached reading — git fetch origin main and branch from the current tip.

The defect, and the three ways to fix it

os doctor --scan-deprecations prescribes objectstack codemod v2-to-v3, a command that does not exist. The docs already admit it. Triage's instruction is "point the hint at the registered os migrate meta, or gate/remove it — smallest honest change wins."

⭐ Note what makes this more than a string swap: the failure mode is a tool confidently telling an operator to run something that cannot work. That is the same family as the two defects this lane landed today — os datasource validate passing over drift it never read, and os doctor printing ✓ over a tree it never walked. A wrong prescription is worse than no prescription, because the operator spends their time on it before finding out.

So the bar for your choice is: does the hint, as it ends up, name something that actually exists and actually does the job?

• ⛔ Do not repoint it at os migrate meta without first verifying that command is registered and that it does what a v2-to-v3 deprecation sweep needs. Re-pointing a bad hint at a different command that doesn't fit is the same defect with a new spelling.
• If nothing registered does the job, gating or removing the line is the honest answer and is explicitly permitted here. Saying nothing beats saying something false.
• Whichever you pick, say in your report which registered commands you checked and how, not just which one you chose.

Fences

• ⛔ os doctor prints ✓ Test coverage / ✓ Deprecations about a tree it never examined (in any user app) #10679 / PR fix(cli): withhold doctor's ✓ over a tree it never examined (#10679) #10799 is landed and is not yours to revisit. Do not touch the MonorepoTreeScan work, the ✓ scoping, or the Not built gate. If your change appears to need one of those, stop and report.
• ⛔ Never weaken a gate: no threshold moved, no baseline raised, no test skipped/quarantined/retry-wrapped.
• ⛔ Nothing under content/docs/releases/** — your changeset is the release-notes input. If a docs page states the command exists, that page is evidence, not necessarily something to edit under this card; report it if it needs a change.

premise_still_valid: false is a legitimate delivery if the hint already names a real command at head.

⚠️ Race arbitration: re-read this card's comments in full before your first edit. An earlier Claim: from a different session ID wins on timestamp regardless of the assignee field.

---

Generated by Claude Code