finding(gate): no gate covers "a doc comment prescribes a local call-site spelling" — the class has now cost #7627 and #7638, and #7617 was mis-cited for it twice

[claude]

Filed by the domain:ui PM seat from the objectui#7638 flight (its second open question). Measured, not fixed.

The defect class

A JSDoc or doc comment on an exported hook/helper prescribes a spelling for what callers should pass. Call sites copy the prose. The prose then outlives the ruling it encoded, and every copy is seeded from it. Fixing the call sites without fixing the prose re-seeds them.

Measured cost so far: two cards (objectui#7627, objectui#7638) and three copied call sites.

⚠️ objectui#7617 does NOT cover this, and both the card and the PM ruling said it did

This is the part worth recording, because the mis-citation happened twice — in objectui#7638's card body and then in the PM's dispatch ruling, which repeated it from the body without checking.

Proven with a lit control rather than by silence:

• objectui#7617 modified scripts/check-spec-symbol-derivation.mjs, whose rule 4 judges citations of @objectstack/spec at member granularity.
• Baseline: exit 0, with 0 mentions of useNavigationOverlay.ts.
• Plant a dangling NavigationConfigSchema.zzzNotARealMember citation in that same doc block → gate goes to exit 1, naming the file at :190.

So the gate does read the file. It simply has nothing to say about prose that prescribes a local call-site spelling and cites no spec symbol. The zero was a reading, not a dead instrument.

Options

• A — leave it at per-hook source pins like the narrow one shipped in PR fix(react/plugins): the record-page URL follows the record source, not the top-level key #7648. Cheap and precise, but only ever covers hooks somebody already got burned by.
• B — a general gate: for any exported hook or helper whose JSDoc @example assigns a parameter, require the example's spelling to match what the in-repo call sites actually pass. Catches the class before the copies exist.
• C — do nothing; treat it as review discipline.

PM recommendation: B, but it is a gate-budget call

Two cards and three copied call sites is roughly the point at which a gate pays for itself in this repo. But this seat already has objectui#7644 building one gate with objectui#7646 queued behind it, so landing a third gate build is a budget decision for the maintainer rather than something a PM seat should assume.

Nothing is unprotected while this is pending: option A shipped in PR #7648 as a narrow source-text pin holding that one doc block shut.

Refs: objectui#7638 (origin) · objectui#7627 (the first instance) · PR #7648 (the narrow pin) · objectui#7617 (mis-cited, twice) · objectui#7644 · objectui#7646.

---

Generated by Claude Code