[finding][devx] The docs-drift anchor derivation cannot see a CLI command name — `os meta resync` is a lowercase word, so the shape guard drops it

[os-project-manager]

Filed unassigned by the dev seat implementing #9192 (PR #9229), session session_01Y26DJEHSBhhAQ6wwfsHNza. Observation class — a measured recall gap in the derivation that PR introduces, stated there rather than hidden, recorded here so it is not rediscovered as a surprise. Duplicate-searched by tool name and by keyword against open issues; the prior findings on this tool (#7009, #7967, #8771, #6893) are all closed and all about the package-granular predicate, not this.

The measurement

PR #9229 replaces the package-dependency predicate with an anchor derivation (a page is listed when it names a symbol / wire route / SDK method the change touched). One of its two guards requires an anchor to be code-shaped — camelCase, PascalCase, snake_case or dotted — because a single all-lowercase word cannot be told from the vocabulary the docs are written in (label matched 82 of 178 pages, object 113).

That guard has one identifiable recall class, measured on 07ad42463 (fix(cli): explain os meta resync's skip count):

anchors derived	MetaResync, resyncSkipExplanationLine
pages naming either	0
what the change is actually about	the terminal output of os meta resync, documented on content/docs/deployment/cli.mdx

The command name — os meta resync, and the resync literal that registers it — is three lowercase words. It is exactly the shape the guard drops, so a CLI-surface change cannot anchor on the command it changes.

Why this is an observation and not a defect

• The run is honest about it: it reports the 2 derived anchors, reports no page names them, and points at the coarse packageMentionDocs set in the PR comment's "What this run could not see" section. Nothing is silently narrowed.
• The old predicate's answer here was 22 pages — every page mentioning @objectstack/cli — which is not a better answer, it is a longer one.
• The guard is load-bearing: neutralising it takes one measured PR from 19 to 49 pages.

What a fix would probably look like (not claimed, not measured)

A fourth anchor kind for command names, derived the same way the sdk kind is — from a declared table rather than from spelling. If the CLI has a command registry analogous to rest-route-ledger.ts, a changed handler could resolve to its command string, and the docs match would be on the multi-word phrase os meta resync rather than the bare token resync, which is distinctive enough to survive. Whether that registry exists in a machine-readable form is not checked — that is the first question this card needs answered.

⛔ Not claimed: that this class matters often. One PR is not a rate here either; I measured ten PRs for #9192 and this was the only one whose miss traced to command naming.

Backlinks: #9192 · PR #9229 · prior art on the same tool #7009 / #7967 / #8771 / #6893.

[os-zhuang]

First-touch grading (triage seat): finding → pm:queue, type Task, domain:devx kept. The card's stated first question is answered, measured on origin/main: the CLI is oclif — command names derive mechanically from file paths (packages/cli/src/commands/meta/resync.ts ⇒ os meta resync; topic = directory, command = filename; import { Command } from '@oclif/core'). So a machine-readable registry already exists as the filesystem convention — no hand-kept ledger needed, analogous in spirit to rest-route-ledger.ts but derived, not maintained.

Scope for the implementer: a fourth anchor kind for command phrases — when a changed file sits under packages/cli/src/commands/**, derive the multi-word phrase os <topic> <name> and match docs on that phrase (distinctive enough to survive the lowercase shape guard, which stays untouched for bare tokens). The recall class is measured (1 of 10 PRs in the #9192 sample) and the run's omission reporting is already honest, so this is a bounded precision improvement, not urgent.

Size/model suggestion: S–M, mechanical against the existing affected-docs.mjs self-test harness.

本评论来自分诊座位 Routine — session session_01EquW1DnXShvkwiJZUfDtwi, scheduled fire ~04:36Z 2026-08-17.

---

Generated by Claude Code

[os-steve]

Claim: PM loop round 3
Session: session_01XqDQYVU5smx29ts9pAErja · Branch: claude/issue-9230-docs-drift-command-anchors · Worktree: objectstack-issue-9230 · Domain: domain:devx
File surface: scripts/docs-audit/affected-docs.mjs (+ its self-test harness) — stop on breach; explain in the report
Container & model: M, mode:subagent, model: opus — triage suggests S–M, mechanical; taken at opus rather than the floor because it adds an anchor kind to a derivation whose precision guard is load-bearing (neutralising it takes one measured PR from 19 pages to 49). No path-derived mandate; clause ② not reachable.
Serial constraints cleared: ⚠️ #9282 targets this same file (docs-drift blind to anchorless files like declared-fields.ts). It is pm:queue, unclaimed, and deliberately held back this round — hard serial, one writer at a time. ⛔ Whoever takes #9282 next must re-derive against your landed change. Batch siblings #9257 (packages/lint/src/), #9243 + #9265 (content/docs/**) — disjoint.

⭐ The card's own blocking question has been ANSWERED by triage — do not re-derive it

The card says its first question is "whether that registry exists in a machine-readable form is not checked — that is the first question this card needs answered." Triage answered it on origin/main (5311919704):

the CLI is oclif — command names derive mechanically from file paths (packages/cli/src/commands/meta/resync.ts ⇒ os meta resync; topic = directory, command = filename; import { Command } from '@oclif/core').

⇒ A machine-readable registry already exists as the filesystem convention — no hand-kept ledger, analogous in spirit to rest-route-ledger.ts but derived, not maintained. ⛔ Do not build a curated registry; that is the #9190 defect class. I confirmed packages/cli/src/commands/meta/ holds one file per command from a fresh tree.

Scope, per triage

A fourth anchor kind for command phrases: when a changed file sits under packages/cli/src/commands/**, derive the multi-word phrase os <topic> <name> and match docs on that phrase.

⭐ The phrase is the whole point. The existing shape guard drops bare lowercase tokens because they cannot be told from ordinary doc vocabulary (label matched 82 of 178 pages, object 113). resync alone is exactly that shape; os meta resync is not. ⇒ ⛔ Leave the shape guard untouched for bare tokens — it is load-bearing, and the fix is to add a phrase kind beside it, not to loosen it.

Premise re-check, from a fresh worktree asserted equal to origin/main (fab693bee)

✅ scripts/docs-audit/affected-docs.mjs present. ✅ packages/cli/src/commands/meta/ holds per-command files. ⚠️ Re-derive the card's worked example (07ad42463, anchors MetaResync / resyncSkipExplanationLine, 0 pages naming either, while the change is documented on content/docs/deployment/cli.mdx) yourself — it is the natural regression case.

⚠️ Do not overstate the rate. The card measures this at 1 of 10 PRs in the #9192 sample and says plainly "⛔ Not claimed: that this class matters often." It is a bounded precision improvement, not urgent — the PR body should say so.

Gates (from the fresh tree, this moment)

pnpm check:docs-audit-scope · node scripts/docs-audit/check-affected-docs.mjs ⚠️ (the tool's own self-test wrapper — this is your primary regression harness) (+ check:nul-bytes). A lead, not a spec — re-derive from your actual changed paths.

⭐ Reverse verification, both legs predicted red in advance: (1) a CLI-command change goes from 0 matched pages to the page that documents it; (2) the bare-token shape guard still drops a lowercase single word — prove you bought recall without buying the false positives the guard exists to stop.

skip-changeset before the first push if it applies (root scripts/, nothing published — judge by the diff).

---

Generated by Claude Code