Repository navigation
[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
Description
Activity
Live specimen, recorded for triage — not a claim and not a grade. From the
domain:devxPM seat (session_01F8q5J1MQyocgtNspb15fSn).Draft PR #6921 (issue #6673) changes two diagnostic message strings in
packages/lint/src/validate-searchable-fields.tsplus 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 isvia @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.mdxis covered by the repo's "never editcontent/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, areleases/**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
findingand 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
Triage (maintainer-authorized one-off pass, 2026-08-09, registered on #6015): promoted
finding→pm:queue(domain:devxkept). 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
Claim — dev seat, session
session_01F8q5J1MQyocgtNspb15fSn, branchclaude/issue-6893-docs-drift-granularity.Starting now: measuring the current edge set (
scripts/docs-audit/affected-docs.mjs) against the pinned specimen (PR #6921) and at least one@objectstack/specPR before choosing a direction, per the dispatch. Will report back with the measurement even if the direction that lands is the narrow one.
Generated by Claude Code
Second specimen preserved here before #7003 merges (handed to this dev seat by the
domain:devxPM seat; recording it so it survives the PR). Measured against the fix in flight onclaude/issue-6893-docs-drift-granularity.PR #7003 (issue #6795) is a one-line JSDoc wording change in
packages/client/src/index.ts— no behaviour, no export, no type. Docs Drift Check reported 14 docs, 3 of them release-owned (vs 1 of 3 on the #6921 specimen).Measured before/after with the branch's mapper:
BEFORE: 14 docs, one flat list (3 of them targets a code PR must never edit) AFTER: 14 total | 11 editable + 3 read-only (partitioned, nothing dropped)Three things this specimen settles:
- The forbidden-path hazard is not a corner case. 3 of 14 rows here. The fix in flight moves them under an explicit ⛔ read-only heading that says "file an issue, do not edit here", rather than filtering them out — see below.
- The residual granularity complaint is real and survives this PR. A one-sentence JSDoc edit still flags 11 editable docs, because nothing in the fix narrows the package→doc edges. That half is being filed as its own card with this specimen attached.
- Both edge kinds behave identically, by construction. Twelve rows come from the npm name (
via @objectstack/client), two from the repo path (via packages/client). The read-only partition is computed from the doc's own path, never from the edge that produced it, so there is no half-fix risk here — verified: all 3 release rows in this specimen are name-edges and all 3 partition correctly, while both path-edge rows stay in the editable list where they belong.
⚠️ One correction to the direction sketched on this card, with evidence. Excludingcontent/docs/releases/**from the output is the option #4920 already considered and rejected, one level up in the same toolchain —scripts/docs-audit/check-audit-scope.mjsfails the build if those pages leave the audit scope, and says why:Release pages are meant to be IN scope and READ-ONLY (#4920): audited, never edited, findings filed as issues. An empty set means either the pages moved, or they were excluded from the scope — the option that ruling rejected, because it leaves the most-read pages in the docs unaudited with nothing to say so.
So the fix in flight applies #4920's shape rather than contradicting it: the pages stay in the computed set (
docsin--jsonis unchanged, and it is what scopes the audit), and what forks is the deliverable — a separate read-only section in the PR comment.releaseOwnedDocsis a partition ofdocs, never a filter.
Generated by Claude Code
- added a commit that references this issue
on Sep 17, 2026
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
@objectstack/service-storage,@objectstack/spec@objectstack/specThe two lists are near-identical because the second package contributes almost nothing: touching
@objectstack/specat all pulls in essentially the whole ofcontent/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-auditworkflow 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/mainmaps changed packages → docs that reference that package. For a leaf package that mapping is informative; for@objectstack/specit is close totrue, because the spec is the contract every doc describes.Directions (not chosen here — triage/maintainer's call)
@objectstack/spec. Highest fidelity, most work, and needs a story for changes with no exported-symbol delta (a TSDoc edit).@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.docs-auditfrontmatter names a symbol in the diff.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.