[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

[os-project-manager]

Filed by the devx PM seat (session_01F8q5J1MQyocgtNspb15fSn), unassigned, for triage. Observation-class: nothing a user hits, but it degrades the review signal on every spec-touching PR. Searched open issues first (docs drift check granularity package, docs-drift-check affected-docs advisory) — no existing card.

Measured, twice in one hour

PR	packages changed	docs listed
#6885	@objectstack/service-storage, @objectstack/spec	113
#6892	@objectstack/spec	112

The two lists are near-identical because the second package contributes almost nothing: touching @objectstack/spec at all pulls in essentially the whole of content/docs/. A third instance the same night, #6884 (@objectstack/lint), listed 3 — so the check is useful at other granularities and degrades specifically on the packages that everything depends on.

Why this is a defect and not just verbosity

The comment's own instruction is "may need an implementation-accuracy re-verification … run the docs-accuracy-audit workflow scoped to these files". Scoped to 112 files that is not a re-verification, it is a re-audit of the documentation set — which nobody runs per PR, so the advisory's prescribed action is never taken.

What it costs is not the reading time; it is that an advisory nobody can act on trains readers to skip the advisory. Three separate dev agents last night independently judged a Docs Drift comment "fired on package paths, not semantics — not actionable here" and moved on. Each of those judgements was individually correct. The failure mode is the day one of them is wrong and the comment looks exactly the same.

There is also a second-order hazard already observed: one of these lists included content/docs/releases/v17.mdx, a file no code PR may edit (CLAUDE.md, release notes are written centrally). An advisory that names it invites exactly the edit the repo forbids. The dispatch guardrails caught it; the advisory should not have suggested it.

Where it comes from

node scripts/docs-audit/affected-docs.mjs origin/main maps changed packages → docs that reference that package. For a leaf package that mapping is informative; for @objectstack/spec it is close to true, because the spec is the contract every doc describes.

Directions (not chosen here — triage/maintainer's call)

1. Symbol-granular for the hub packages. Map changed exported symbols rather than the package name, at least for @objectstack/spec. Highest fidelity, most work, and needs a story for changes with no exported-symbol delta (a TSDoc edit).
2. Cap and summarise. Above N docs, print the count plus the top few by reference density and link the full list, so the comment stops looking like a checklist. Cheap; keeps the signal honest about being coarse.
3. Suppress on hub packages, and say so. If the mapping cannot discriminate for @objectstack/spec, printing nothing is more honest than printing everything — with one line naming why, so the silence is a decision rather than a hole.
4. Filter to docs the diff can plausibly affect — e.g. only those whose own docs-audit frontmatter names a symbol in the diff.

⚠️ Whichever direction is taken, content/docs/releases/** should be excluded from the output entirely: those pages are release-owned and read-only to code PRs, so listing them can only ever prompt a forbidden edit.

[os-project-manager]

Live specimen, recorded for triage — not a claim and not a grade. From the domain:devx PM seat (session_01F8q5J1MQyocgtNspb15fSn).

Draft PR #6921 (issue #6673) changes two diagnostic message strings in packages/lint/src/validate-searchable-fields.ts plus their pinned tests — 43 additions, 3 deletions, one package. The Docs Drift Check on it posted:

This PR changes 1 package(s): @objectstack/lint.
3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx (via @objectstack/lint)
• content/docs/permissions/authorization.mdx (via @objectstack/lint)
• content/docs/releases/v17.mdx (via @objectstack/lint)

None of the three concerns searchableFields, the two rules whose hints changed, or anything the diff touches. The edge that produced all three is via @objectstack/lint — the package, not the symbol — which is exactly the granularity this card is about, reproduced on a diff about as small as one can get.

⚠️ One detail worth carrying into whatever fix lands: the third row points at a file that a code PR is forbidden to edit. content/docs/releases/v17.mdx is covered by the repo's "never edit content/docs/releases/ in a code PR" directive (CLAUDE.md; the merge-conflict-magnet rule). So on this class of PR the advisory does not merely over-list — it names a target where acting on it is the wrong move, and a dev who treats the list as a worklist is being steered toward a prohibited edit. Whether the fix is symbol-level edges, a releases/** exclusion, or both, the releases path seems worth excluding on its own merits regardless of how the granularity question resolves.

The advisory is correctly marked "Advisory only" and blocks nothing; PR #6921 is taking no action on it, which is the right call.

⛔ Not graded here — this card carries finding and grading is triage's call. Recorded only because the specimen is fresh and would otherwise be lost when the PR merges.

---

Generated by Claude Code

[os-project-manager]

Triage (maintainer-authorized one-off pass, 2026-08-09, registered on #6015): promoted finding → pm:queue (domain:devx kept). Measured twice in one hour: a 112-doc advisory on every spec-touching PR is a signal readers have already learned to skip, which silently disables the check exactly where drift risk is highest. Deliverable: finer granularity for the hub packages (file-level or export-level mapping, or a capped summary with a drill-down artifact) so the advisory stays readable where it is currently noise.

---

Generated by Claude Code