[devx] Docs Drift Check edges are still package-granular: a one-line JSDoc edit in @objectstack/client lists 11 docs, a spec src change 106

[os-project-manager]

Filed unassigned for triage by the dev seat that implemented #6893 (PR #7007). This is the half of #6893 that PR deliberately did not attempt, split out because it is a design decision rather than a defect fix, with the measurement attached so the next person does not have to redo it.

Searched open issues first (drift symbol granularity docs affected-docs, "docs drift") — only #6893 itself and unrelated #7002.

What #7007 fixed, and what it left

PR #7007 removed two things from the Docs Drift Check advisory:

• dev-only manifest false positives — a package.json whose changed top-level keys are all in {scripts, devDependencies} no longer counts as a package change. This was the entire cause of [finding][devx] Docs Drift Check is package-granular, so any PR touching @objectstack/spec lists ~112 docs — an advisory that large is one every reader learns to skip #6893's headline "112": PR feat(devx): 给 check:dev-prereqs 补上「陈旧 dist」判定(内容指纹,非 mtime) (#5864) #6892's only packages/ change was one scripts.build line. Measured across 400 merged commits, five commits had a manifest as their sole implementation change, all five dev-only, 152 false rows total, now 0.
• the forbidden-path hazard — content/docs/releases/** rows are now partitioned into a read-only section that says "file an issue, do not edit here", per the docs-accuracy-audit 会就地改写 content/docs/releases/**(9 页),与 AGENTS.md「release-owned,禁止在代码 PR 中编辑」直接冲突 #4920 ruling (they stay in the computed set; only the presentation forks).

It changed nothing about how a changed package maps to docs. That mapping is still: doc text mentions the package's npm name or repo path.

The residual, measured

PR	change	docs still listed after #7007
#7003	one sentence of JSDoc prose in packages/client/src/index.ts — no behaviour, no export, no type	11 editable (+3 read-only)
#6885	genuine packages/spec/src/** change (storage contract)	106 editable (+7 read-only)

#7003 is the sharper specimen of the two: if package granularity cannot tell a prose-only JSDoc reword from a semantic change, the "may need an implementation-accuracy re-verification" claim carries essentially no information on that class of PR.

Why #7007 did not narrow the edges

Two reasons, both worth the maintainer's attention before anyone starts:

1. It contradicts a stated design principle in the tool itself. scripts/docs-audit/affected-docs.mjs says, in its header: "Over-inclusion is intentionally preferred over misses; the periodic FULL audit is the backstop for docs that describe a package without naming it." Narrowing to symbols or exports trades that the other way. That is a legitimate trade to make — but it is a decision about what the check is for, not a bug fix, and it should be made deliberately.
2. A narrower edge that misses a doc is strictly worse than a wide one that over-lists, because catching drift is the whole point. The failure mode is invisible: the comment gets shorter and looks better while quietly reporting less.

Two edge kinds, both of which any narrowing must handle

On #7003, 12 rows came from the npm name (via @objectstack/client) and 2 from the repo path (via packages/client). These are separate arms of the matcher. Narrowing one and leaving the other yields a half-fix that looks complete on whichever specimen you happen to test.

Directions (unchanged from #6893, none chosen)

1. Symbol / export granular. Map changed exported symbols rather than the package name. Highest fidelity; needs a story for changes with no exported-symbol delta — which is exactly fix(client): QueryOptionsV2 no longer calls itself the recommended interface for deprecated data.find() #7003, a JSDoc edit that changes no symbol at all. Does that class report nothing, or everything?
2. Cap and summarise. Above N docs print the count plus the top few by reference density, with the full list behind a drill-down. Cheap, honest about being coarse, changes nothing about what is computed. fix(devx): docs drift check —— dev-only manifest 改动不再点亮整包文档，release 页改为只读分区 (#6893) #7007 deliberately did not do half of this: choosing N and the ranking belongs with whoever owns the granularity question.
3. Filter to docs the diff can plausibly affect — e.g. only those whose own frontmatter names a symbol in the diff. Note that hand-written docs currently carry no such frontmatter (checked: title / description only), so this direction implies authoring it first.

Reproducing the measurement

node scripts/docs-audit/affected-docs.mjs --json origin/main

docs is the full set, releaseOwnedDocs its read-only subset, detail[].via names the edge kind that produced each row.

[os-project-manager]

Triage (pass #2, 2026-08-09, registered on #6015): held as finding, routed domain:devx. PR #7007 already removed the headline noise (the dev-only manifest false positives that produced #6893's 112). Whether the residual package-granular edges (11 docs for a one-line JSDoc edit) still induce reader-skip is now an open empirical question, and symbol-level edges are a real engineering investment. Restart condition: a post-#7007 measurement window shows spec/client-touching PRs still listing enough docs that reviewers demonstrably skip the advisory — escalate then with the numbers, which this card already carries the method for.

---

Generated by Claude Code