diff --git a/.github/workflows/docs-drift-check.yml b/.github/workflows/docs-drift-check.yml
index a658920b38..97ef030f57 100644
--- a/.github/workflows/docs-drift-check.yml
+++ b/.github/workflows/docs-drift-check.yml
@@ -1,10 +1,18 @@
name: Docs Drift Check
-# When a PR changes packages/** code, flag the hand-written docs that reference the
-# affected packages so they can be re-verified for implementation accuracy before the
-# drift lands on main. Advisory only — posts a PR comment, never fails the build.
-# The actual LLM audit is run on-demand / on a schedule via the `docs-accuracy-audit`
-# workflow, scoped to exactly the docs this check lists.
+# When a PR changes packages/** code, flag the hand-written docs that NAME something the
+# change touched — a symbol, a wire route, or the SDK method a route ledger binds to it —
+# so they can be re-verified for implementation accuracy before the drift lands on main.
+# Advisory only: posts a PR comment, never fails the build. The actual LLM audit is run
+# on-demand / on a schedule via the `docs-accuracy-audit` workflow, scoped to exactly the
+# docs this check lists.
+#
+# It used to list pages by PACKAGE DEPENDENCY ("which docs mention @objectstack/x"), and
+# #9192 measured that wrong in both directions on a real PR: 2 of 3 listed pages were
+# irrelevant, and the 2 pages that actually documented the changed surface were missing
+# because they document it through the SDK, which does not depend on the implementing
+# package. The comment now also states what the run could NOT see — the derivation being
+# read past its precision, with its silence taken for absence, is what #9192 records.
on:
pull_request:
@@ -75,6 +83,30 @@ jobs:
const docs = data.docs || [];
const pkgs = (data.changedPackages || []).map(p => p.name || p.dir);
const marker = '';
+ // #9192 — the derivation now matches pages that NAME something the change
+ // touched (symbol / route / SDK-method anchors) instead of pages that merely
+ // mention a changed package. Everything the derivation could NOT see is
+ // stated in the comment, at the point of use: the failure this fixed was not
+ // the tool lying, it was a reader taking its silence for absence.
+ const anchorList = data.anchors || [];
+ const anchorless = data.anchorlessChanges || [];
+ const overbroad = data.overbroadAnchors || [];
+ const crossCutting = data.crossCuttingSymbols || [];
+ const weak = data.weakAnchorsDropped || [];
+ const coarse = data.packageMentionDocs || [];
+ const rederive = `node scripts/docs-audit/affected-docs.mjs --json origin/${baseRef}`;
+ const limits = [];
+ if (anchorless.length) limits.push(`**${anchorless.length}** changed file(s) yielded no anchor (\`${anchorless.slice(0, 3).join('`, `')}\`${anchorless.length > 3 ? ', …' : ''}) — pages documenting those are invisible to this run`);
+ if (crossCutting.length) limits.push(`**${crossCutting.length}** cross-cutting symbol(s) contributed no route anchor: \`${crossCutting.join('`, `')}\``);
+ if (overbroad.length) limits.push(`**${overbroad.length}** anchor(s) matched too much of the corpus to be a work list: \`${overbroad.join('`, `')}\``);
+ if (weak.length) limits.push(`**${weak.length}** name(s) were too generic to anchor anything (single lowercase words)`);
+ // Rendered whenever there is anything to say, INCLUDING when the only thing to
+ // say is "the wide net exists and holds N pages". A short list is the right
+ // answer here, but a reader must be able to tell a short list from a blind one
+ // without leaving the PR.
+ const limitsBlock = (limits.length || coarse.length)
+ ? ['', 'What this run could not see
', '', ...limits.map(l => `- ${l}`), ...(limits.length ? [''] : []), `Coarse fallback — **${coarse.length}** page(s) merely *mention* a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): \`${rederive}\` → \`packageMentionDocs\`.`, '