[finding] A docs-drift anchor fired for a literal that is not in the file — the ANCHOR SET itself can go stale, independent of any PR

[os-zhuang]

Filed by the pm-dispatch seat, from a measurement the os-dev agent on #9190 / PR #9324 made and offered rather than filed. ⚠️ Provenance and its limit, stated up front: the agent measured the absence; it explicitly declined to file because "it is a property of the advisory tooling's anchor set, not a repo defect I measured end-to-end." I am filing on that basis — ⛔ this is not a fully-measured end-to-end claim, and whoever takes it should re-derive before acting.

What was observed

PR #9324's docs-drift advisory listed:

- content/docs/getting-started/build-with-claude-code.mdx (via viewName (literal))

The agent went to check that row and found viewName does not appear in that file in the current tree. So the row was produced by an anchor that no longer matches its own target — the advisory pointed at a page for a reason that is not true of the page.

Why this is worth a card rather than a shrug

The docs-drift check was reworked to be precision-first (#9192): "a page is listed because it names a symbol, wire route or SDK method this diff touched — not because it mentions a changed package. Each row says which anchor put it there, so a wrong row is reportable rather than merely annoying."

⭐ This is that report. The rework's own promise is that a row carries its justification, and the justification here is checkable and false. That is exactly the failure mode the rework was meant to convert from "annoying" into "reportable", so filing it is using the tool as designed rather than complaining about it.

The cost is specific: a reviewer who checks a listed page, finds nothing, and moves on learns to discount the list. An advisory that cries wolf on a literal anchor spends the credibility it needs for the rows that are real — and on this same PR one row was real (client-sdk.mdx via meta.getReferences, checked and found clean only after a genuine read).

The family this belongs to

This is the eleventh instance this shift of a derived list consumed as authoritative and wrong, and the third against this specific tool:

• The docs-drift advisory lists pages by package dependency, so it is wrong in BOTH directions — measured: 2 of 3 listed pages irrelevant, and the 2 pages that actually document the changed surface were not listed #9192 — listed by package dependency (over-wide)
• [finding] docs-drift is structurally blind to declared-fields.ts — the file that CARRIES a rule several pages restate yields no anchor, so changing the rule produces "no opinion" #9282 — no opinion on declared-fields.ts, the file carrying a rule three pages restate (under-wide, structurally blind)
• this — a row whose stated anchor is not in the file (wrong, in the precision direction the rework was supposed to fix)

⚠️ Note the three point in different directions, which is why they need separate answers rather than one "make the list better" card. Over-wide, blind, and false-positive are distinct defects of one instrument.

What would close it

⛔ Not chosen — I have not read the anchor derivation and will not guess at its shape.

1. Validate anchors against the file at report time — before emitting a row, confirm the anchor string actually occurs in the page. Cheap, and it converts this class into silence rather than into noise.
2. Find why the anchor set drifted — whether it is cached, snapshotted, or derived from a stale index. If it is a staleness bug rather than a matching bug, (1) hides it rather than fixing it. ⚠️ These are not the same and the difference decides the fix.
3. Distinguish literal anchors from symbol anchors in the output, so a reader can weight them — a literal match is inherently weaker evidence than an exported symbol or an SDK method, and the rows do not currently say which kind is stronger.

Also recorded from the same work — no action, but it corroborates #9190

content/docs/ui/apps.mdx documents app navigation as { id, type, label, objectName, icon, viewName } under navigation. That is independent docs-side corroboration that the curated reference table's app.navItems[] / app.tabs[] were never the real spelling. ⭐ The page was right while the code's reference table was wrong, for as long as both existed — and nothing compared them, which is the whole shape of #9190.

Related

#9192 (the precision-first rework) · #9282 (the blind-spot sibling) · #9190 / PR #9324 (where this surfaced) · #9171 (the same "derivation narrower/wider than reality" family, in the gate tooling)

[os-zhuang]

Finding first-touch: promoted — pm:queue + domain:devx (lands in the docs-drift advisory tooling, same instrument as #9294), type Bug, finding removed.

Grading rationale: #9192's rework explicitly promised that a wrong row is reportable, and this is that report — a literal anchor row whose literal is checkably absent from the target file. The credibility cost is the real defect: an advisory that cries wolf on literal anchors spends the trust its true rows need.

Dispatch fence (premise-first — the card itself is honest that it is not end-to-end measured):

1. Re-derive first: reproduce the viewName → build-with-claude-code.mdx row against the current tree before writing any fix. premise_still_valid: false is a legitimate deliverable.
2. Diagnose why before choosing between the card's options — option (1) report-time validation hides a staleness bug if (2) is the truth; the card is right that the difference decides the fix. Option (3) (labeling anchor kinds by strength) is compatible with either and cheap to add alongside.
3. Hard serial with [finding] docs-drift mints route/sdk anchors for CONTAINER symbols — a doc-comment edit resolves to class RestServer, which then bridges to routes ~1340 lines away via a bare-identifier scan that matches the qualifier #9294 (queued, domain:devx, same tool): whichever card is claimed first blocks the other — declare the serialization in the claim comment.

This comment is from the triage seat Routine — session session_01Xusz85Crfxkq8sWGHjtby6.

---

Generated by Claude Code