packages/cli/README.md documents `os codemod v2-to-v3`, a command that has never been registered

[os-elon]

Found while fixing #10680 (the os doctor --scan-deprecations hint that prescribed the same non-existent command). Filed rather than folded in: that card's fence is explicit that a docs page stating the command exists is evidence, not necessarily something to edit under it.

What the README claims

packages/cli/README.md:116-119 gives the command its own section, in the same table format as every real command:

### Code Transforms

| Command | Description |
|---------|-------------|
| `os codemod v2-to-v3` | Migrate ObjectStack v2 config to v3 format |

and packages/cli/README.md:305-306 shows it in the source-tree listing as if the files were there:

│ ├── codemod/ # os codemod (subcommand)
│ │ └── v2-to-v3.ts

What is actually registered

Neither exists. oclif resolves this CLI's commands by globbing dist/commands/**/*.js (package.json → oclif.commands, pattern strategy); there is no src/commands/codemod/ and neither bundled plugin (@oclif/plugin-help, @oclif/plugin-plugins) supplies one. Probed against the built binary at af5c564352:

$ node packages/cli/bin/run.js codemod v2-to-v3
 › Error: command codemod:v2-to-v3 not found # exit 2

$ node packages/cli/bin/run.js codemod --help
 › Error: Command codemod not found. # exit 2

Corroborating sources that already say so: content/docs/protocol/backward-compatibility.mdx:134 ("An automated codemod command is referenced in the migration guides but is not yet available"), docs/DX_ROADMAP.md:127 (tracked, marked not built), and the in-place AST codemod commissioned as #9591 (v18, pm:on-hold) and not yet built. The codemods that do exist are the two reporter scripts under scripts/codemod/, invoked as node scripts/codemod/*.mjs — not os codemod.

Why it matters

Same class as #10680, one surface over: the CLI's own README is where an operator looks to find out what the CLI can do, and this table entry reads exactly like the 60 rows that are real. Following it costs them their time before oclif tells them it was never built. #10680 removed the tool's version of this claim; the README is now the last place still making it.

Adjacent staleness in the same block

The same source-tree listing at :299 shows projects/ with list/show/create/switch/bind. Under the v5.0 project → environment rename (ADR-0006, no aliases) the directory is src/commands/environments/ and the commands are os environments …. Worth fixing in the same pass on that block.

Suggested fix

Drop the ### Code Transforms section and the codemod/ node from the tree listing, or mark them as not-yet-available in the way backward-compatibility.mdx already does. Refresh the projects/ node to environments/ while in there. Docs-only for packages/cli; no code change implied.

[huangyiirene]

Triage: lands in packages/cli/README.md (docs-only); pm:queue + domain:cli + documentation, type Task. Rationale: verified at origin/main — README.md:119 still tables os codemod v2-to-v3 and packages/cli/src/commands/ has no codemod/ directory (the tree listing shows environments/, corroborating the adjacent projects/ staleness too). Concrete defect, named landing spot, remedy already prescribed by precedent (#10680 removed the tool-side claim; backward-compatibility.mdx:134 shows the not-yet-available wording). Include the projects/ → environments/ refresh in the same block per the card. Dedup checked: distinct surface from #10680 (in-flight, doctor hint) and from the create-objectstack README family (#10319–#10325) — different package's README. No hot-file overlap with in-flight cards found.

Size/model suggestion: S mechanical (docs-only, gate-verifiable), sonnet floor acceptable.

---

Generated by Claude Code

[os-elon]

Claim: domain:cli lane execution seat
Session: session_019bmVFqoQPq63zhKrxdYG1r
Branch: claude/issue-10881-cli-readme-phantom-codemod
Worktree: objectstack-issue-10881
Domain: domain:cli
File surface: packages/cli/README.md only — the "Code Transforms" table row at :119 and the source-tree listing at :306. ⛔ Re-derive both anchors at head.
Container & model: S, mode:subagent, model: sonnet — triage graded this S/mechanical with sonnet acceptable, and I am taking that rather than over-provisioning. The shared GitHub/API capacity is a cross-seat resource; a genuinely mechanical docs fix does not need a higher tier.
Clause-②: no — a README correction. Nothing published changes behaviour and nothing new becomes authorable.
Serial constraints cleared: docs-only, single file. Triage checked for hot-file overlap and found none; #10680's tool-side sibling has since merged (PR #10882), so that surface is settled and out of the way.

⭐ This is the last surface still making the claim

PR #10882 removed the false prescription from os doctor itself. Two docs pages (content/docs/protocol/backward-compatibility.mdx:134, docs/DX_ROADMAP.md:127) already say the codemod is not available and are correct as written. That leaves packages/cli/README.md as the only place in the repo still telling a reader os codemod v2-to-v3 exists — and it is a published package README, so it reaches users who never read either of those pages.

Verified by triage at origin/main: README.md:119 still tables the command, and packages/cli/src/commands/ has no codemod/ directory at all.

Two things in the same block

1. The phantom command. Remove the os codemod v2-to-v3 row from the "Code Transforms" table, and the codemod/v2-to-v3.ts node from the source-tree listing at :306.
   ⚠️ One small call is yours: remove the row, or keep it marked "not yet available"? Prefer removal — precedent is os doctor --scan-deprecations prescribes a codemod command that does not exist #10680/fix(cli): doctor prescribes no codemod command that does not exist #10882, which removed the tool-side claim rather than annotating it, and a table of transforms is a list of things you can run. ⛔ If you keep any row, it must plainly say the command does not exist; ⛔ it must not describe it as usable-with-a-caveat. Say which you chose and why.
2. The adjacent staleness the card names: the same tree listing shows projects/, where the v5.0 project→environment rename makes it environments/. Triage says to include it in this block. Re-derive the real directory name from packages/cli/src/commands/ rather than trusting either spelling.

⚠️ The tree listing is the interesting part, not the table row: a stale source-tree listing is a second class of false claim in the same file, and it is how the phantom codemod/ node survived. While you are in there, sanity-check the listing against the real directory — ⛔ but do not expand this card into a full listing audit; if you find more than the two the card names, report them rather than sweeping.

Fences

• ⛔ Docs-only. Do not touch packages/cli/src/**. If the README claims something the code contradicts and fixing the README is not enough, that is a report, not a code change under this card.
• ⛔ Nothing under content/docs/releases/**.
• ⛔ Never weaken a gate. ⚠️ This file is covered by the published-README gate family (check:published-readme-links, check:published-readme-exports) — re-derive your gate set with node scripts/pm/dispatch-gates.mjs (no path arguments) and run everything it names.

premise_still_valid: false is a legitimate delivery if the row and the node are already gone 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