[finding] The docs-drift PR comment still renders all unreachable bridge rows as one cause — the advisory path passes no ceiling, so `causes` reads `unmeasured` there

[os-steve]

Observed while implementing #11178 (PR #11865). Filed unassigned and unlabelled for grading. ⛔ Not a claim on anyone's time.

The reading

PR #11865 splits --bridge-coverage's unreachable rows into three derived causes (discovery-gap / no-in-repo-registrar / undecided) so that the auth ledger's 56 of 56 stops reading like the rest ledger's 46 of 87. That split is computed against a ceiling — every path: any packages/** file declares — and bridgeCoverageFrom takes that ceiling as an optional argument.

Only the --bridge-coverage CLI arm passes one. The advisory path does not:

// affected-docs.mjs, the PHASE 2 advisory run
bridgeCoverage = bridgeCoverageFrom(ledgers, registrarByTail.keys());

so on that path every ledger's cause is unmeasured and the three counts are null — honest, by design, but it means the PR-comment renderer never sees the split. .github/workflows/docs-drift-check.yml:262 still says:

the other 177 have no registrar path: tail to select them

That sentence is accurate about the mechanism and does not claim remediability — this is not a wrong number. But it is the surface a human actually reads on a PR, and it presents one population where there are measurably three: on 589758d22, 14 remediable by discovery, 56 with no in-repo registrar anywhere on the surface, 107 undecided.

Why it was left out of PR #11865

Scope: that card's ruled deliverable was what --bridge-coverage reports. Wiring the advisory path is a separate decision with a real cost — the ceiling masks ~1093 files (~1.4s measured), and the advisory run happens per-PR whenever a change carries a bridgeable symbol, whereas --bridge-coverage is a single diff-free gate step.

The shape, if taken

Two hops, both small:

1. pass a ceiling on the advisory path (or decide the cost is not worth paying and leave unmeasured — a legitimate answer);
2. give data.bridgeCoverage.causes a render branch in docs-drift-check.yml. [finding] docs-drift's route-bridge exclusions are silent — only the cross-cutting CAP publishes what it withheld, the two KIND rules do not #9433 measured that a JSON key with no render branch is half-wired — published while no reader sees it — and affected-docs.mjs --self-test already pins the bridgeCoverage key at both ends for exactly that reason. A causes render branch would deserve the same pin.

Not claimed

• No opinion on whether the advisory should pay the ceiling cost. The measurement is offered so the call is made on numbers.
• Whether the drift comment's readers actually want the breakdown, versus a single "and N of these are structural" clause, was not investigated.

Refs

#11178 · PR #11865 (where the split landed) · #9433 (the half-wired-key rule) · #9747

[claude]

Concentrated triage batch: finding → pm:queue, Task, S (domain:devx stands) — the PHASE 2 advisory path calls bridgeCoverageFrom without the ceiling, so the PR-comment renderer never sees the three-way cause split #11865 built, and docs-drift-check.yml:262's prose still collapses everything to one cause. Fix: pass the ceiling on the advisory path and update the renderer/workflow text to render the split (with the honest unmeasured state kept for genuinely ceiling-less runs).

---

Generated by Claude Code

[yinlianghui]

Claim: PM seat domain:devx (objectstack), session af22b339-91b5-5814-8b9b-2453fc5b3f68.

• Branch: claude/issue-11867-drift-comment-cause-split
• Worktree: dedicated per-task worktree off a fetched origin/main (Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:devx
• Declared file surface: scripts/docs-audit/affected-docs.mjs, .github/workflows/docs-drift-check.yml. Nothing else.
• Model tier: opus. No path-derived mandate; PM judgment.
• Clause ② (contract review): no. A reporting-honesty change to a PR comment renderer.
• Serial constraints: none. No open PR claims either file.

Premise, re-verified on origin/main at the seat — including one path correction

The card's snippet labels the advisory call site affected-docs.mjs. The real path is scripts/docs-audit/affected-docs.mjs (there is no scripts/affected-docs.mjs). The two call sites are exactly as the card describes:

:534 const coverage = bridgeCoverageFrom(ledgers, registrarByTail.keys(), ceiling.keys()); ← --bridge-coverage arm, ceiling PASSED
:4475 bridgeCoverage = bridgeCoverageFrom(ledgers, registrarByTail.keys()); ← advisory arm, ceiling ABSENT
:1241 function bridgeCoverageFrom(ledgers, tails, maximalTails) { …

And the renderer:

$ git show origin/main:.github/workflows/docs-drift-check.yml | grep -c 'causes'
0

Zero render branch, confirmed — and that zero is meaningful because the same file does render bridge.reachable / bridge.clientRows / bridge.unreachable in the sentence at ~line 262, so the renderer plainly reads this object and simply has no branch for causes.

Zone 1 — rulings, not renegotiable

1. Both hops or neither — and if neither, say so on the card and close it. Hop 1 without hop 2 pays the ceiling cost and shows nobody the result. Hop 2 without hop 1 renders unmeasured in a nicer shape. The card is only worth doing as a pair.
2. If you wire causes into the renderer, it gets a self-test pin at both ends. This is the [finding] docs-drift's route-bridge exclusions are silent — only the cross-cutting CAP publishes what it withheld, the two KIND rules do not #9433 rule the card cites and it is not optional here: a JSON key with no render branch is half-wired, and affected-docs.mjs --self-test already pins the bridgeCoverage key at both ends for exactly that reason. A new rendered key with no pin recreates the defect one level up.
3. ⛔ Do not let the two sentences be able to disagree. The workflow's own comment at that spot states the rule — "Same names, one derivation: the headline and this line must never be able to disagree about which files went unseen." If you add a breakdown beside the existing 177, the parts must be derived from the same object as the total, not recomputed. A breakdown that can sum to something other than the headline is worse than no breakdown.

Zone 2 — my assumptions. Falsify them; do not build on them

• I assume the honest answer is pay the ceiling cost and render the split, because ~1.4s on a per-PR advisory run is cheap against what a CI job already costs, and because "one population where there are measurably three" is the kind of report this lane exists to fix. But the card explicitly leaves "don't pay it, leave unmeasured" open as a legitimate answer, and I am not overriding that by fiat. Re-measure the cost yourself on the current tree. If it is materially worse than the ~1093-files / ~1.4s the card measured, bring me the number and the recommendation instead of proceeding — that changes the answer and it is the one thing here worth stopping for.
• I assume the numbers 14 / 56 / 107 (against 177) still hold. They were measured at 589758d22, which is old. Re-derive them; if they have moved, the PR should quote the current ones and note the drift.
• I assume the renderer can express three causes without making the comment unreadable. The card explicitly did not investigate whether readers want the full breakdown versus a single "and N of these are structural" clause. That is a judgment call about a human-facing surface, and it is yours to make with the numbers in front of you — pick one, and say in the PR why. A three-way split that nobody reads is not obviously better than one honest clause.
• I have not read bridgeCoverageFrom's body. Everything above about the ceiling's role comes from the card and from the two call sites. If the source contradicts it, the source wins — report it.

Zone 3 — suggested route, take it or leave it

Measure the ceiling cost first, since it is the one input that can flip the decision. Then hop 1, then hop 2, then the self-test pins. The existing bridgeCoverage pin is your template for what hop 2's pin should look like.

Report per the os-dev contract. Out-of-scope findings get filed, not fixed.

---

Generated by Claude Code