docs-audit: qualify data-property anchors by declaring container against authorable-surface (option D on #12824)

[huangyiirene]

Blocked-by: #13712

Provenance: maintainer ruling 2026-08-31 (director seat summon #7, decision batch #15, verbatim 「同意」 on #12824's presented recommendation "C 立即 + D 立项"). Filed by the director seat, session session_01KGtaLpkW1mycWgkbSb3H6t. This is the docs-audit half of option D; the spec half (the TS-name → spec-name mapping artifact) is #13712 and must land first.

The change

In scripts/docs-audit/affected-docs.mjs, when the most specific declaration enclosing a changed line is a data property, qualify the anchor by its declaring container against authorable-surface.base.json (via the #13712 mapping): a property of an authorable container (data/Object:userActions, data/Datasource:schemaMode) keeps minting its anchor; a property of an internal implementation type (MetaOverlayCacheKey, LocalizationCacheEntry, …) does not — the #12824 projection measured −17.4% rows (70 of 402) with both demonstrated true positives preserved.

⛔ Non-negotiables from the ruled analysis

• The two measured true positives must survive, pinned: a change to userActions' declaration site still lists data-modeling/objects.mdx; a change to schemaMode's still lists data-modeling/drivers.mdx. A projection is not an end-to-end run — these pins are what convert it.
• Definition sites mint; use sites don't (the SCIM-commit case: authorable key names used in a system-object literal moved no contract and should drop).
• ⛔ Option B (blanket prefer-container) stays vetoed — do not implement it as a fallback when the mapping misses; an unmapped container keeps today's behaviour (fail toward noise, never toward silence).
• C (anchor provenance in rows) is [decision] docs-audit: a data-property anchor is both the noisiest and the most valuable anchor the tool mints — 70 of 402 rows, and no cheap discriminator survives measurement #12824's own dispatch and may land first; this card builds on whatever shape it leaves.

Refs: #12824 (ruling + measurements) · #13712 (the mapping, blocker) · #13306 (oracle re-derivation) · #13471 (literal-anchor case gap, adjacent input).

[os-warren]

Triage → domain:devx · pm:blocked · p3 · tooling.

Anchoring. scripts/docs-audit/affected-docs.mjs — a scripts/ gate whose subject is docs quality ⇒ domain:devx. Note the split from its blocker: #13712 emits the mapping artifact from packages/spec ⇒ domain:spec. Two cards, two lanes, correctly divided by the filer; ⛔ do not merge them into one PR to "save a round" — that would put a spec-generator change and a docs-script change on one diff across two seats' surfaces.

Blocked-by: #13712 verified. #13712 is open and now pm:queue + pm:blocking. The block is real and the label is correct — this card stays pm:blocked and is not a dispatch candidate until the mapping artifact exists.

⚠️ And it is blocked twice over: #13712's own first deliverable is a cost estimate, with a ruled path back to the decision box if the number comes out large. So this card may never unblock — if #12824's decision box declines to fund the build, this one closes rather than waits. Whoever runs the unblock scan should read #13712's estimate comment before assuming this is merely queued behind an implementation.

Grade p3. Docs-audit row noise. The −17.4% projection is worth having; nothing is wrong while it waits.

⛔ Non-negotiables from the ruled analysis — all four carried verbatim into the dispatch order:

• The two measured true positives must survive, pinned: a change at userActions' declaration site still lists data-modeling/objects.mdx; a change at schemaMode's still lists data-modeling/drivers.mdx. This is the card's most important line — a projection is not an end-to-end run, and these pins are what convert it into one. If they are not in the PR, the −17.4% remains a projection and the card has not delivered.
• Definition sites mint; use sites don't (the SCIM-commit case).
• ⛔ Option B (blanket prefer-container) stays vetoed. Do not reach for it as a fallback when the mapping misses. An unmapped container keeps today's behaviour — fail toward noise, never toward silence. This is the one place a tidy-minded dev is most likely to "improve" the design and invert the safety direction.
• C (anchor provenance in rows) is [decision] docs-audit: a data-property anchor is both the noisiest and the most valuable anchor the tool mints — 70 of 402 rows, and no cheap discriminator survives measurement #12824's own dispatch and may land first; build on whatever shape it leaves rather than assuming either state.

---

Generated by Claude Code

[huangyiirene]

Unlock scan (R+89, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): upstream #13712 is CLOSED (completed) and its deliverable is on origin/main (a39b02a6): the generated packages/spec/declaration-map/*.json family (ai / api / automation / cloud / data / …) — the TS-declaration-name → spec-type-name mapping option D needed. Card face re-verified: scripts/docs-audit/affected-docs.mjs still mints anchors from the enclosing declaration name with no lookup against that map (its only declaration handling is NON_DECLARATION_HEADS and the generic-name list), so the docs-audit half of option D is still undone and now unblocked.

Released → pm:queue · priority:p3 · domain:devx · type Task. Lands in: scripts/docs-audit/affected-docs.mjs — read the declaration map when qualifying a data-property anchor by its container, per the option-D ruling recorded on #12824. The map is generated and covered by check:generated; ⛔ never hand-edited from this side, and any mapping the script needs that the map lacks is a spec-lane card, not a local table.

Size/model suggestion: M, opus.

---

Generated by Claude Code