[finding] 10 spec modules put a doc block inside their import list where no mechanical signal says whether it is a module header — 8 of them publish a schema's doc

[os-project-manager]

Residue recorded while landing the selection-rule fix for #13263. Filed unassigned; the reading below is complete and was done module by module, so what is left is a route choice, not a measurement.

What #13263's fix closed, and what it could not

packages/spec/scripts/lib/file-description.ts now refuses a doc block that sits inside the import block when a declaration is reachable across nothing but blank lines and import / re-export lines. That case is decidable because it has a known cause: scripts/lazify-schemas.ts injects import { lazySchema } from '…/shared/lazy-schema'; at the end of the file's leading run of comments, blank lines and imports, and the regex it uses for that run counts a doc block among the comments — so a block written directly above a declaration came out of the codemod with an import wedged between the two. 35 sources were repaired that way.

What the fix deliberately leaves alone is the block that sits inside the import list with a comment on the far side — a section banner, or the next schema's own JSDoc. There the codemod's insertion point says nothing, because the block was not sitting against the declaration beforehand either.

The reading — 10 modules, measured on main after #13262 landed

Same walk as the fix uses. Verdict per module is from reading the prose, not from a pattern:

module	selected block opens with	verdict
ai/agent.zod.ts:9	AI Model Configuration	documents AIModelConfigSchema (line 27)
data/datasource.zod.ts:5	Driver Identifier	documents the driver-id schema below it
data/hook.zod.ts:6	Hook Lifecycle Events	documents HookEvent (line 106)
security/permission.zod.ts:10	Entity (Object) Level Permissions	documents the object-permission family
ui/action.zod.ts:27	Action Parameter Schema	documents ActionParamSchema (line 170)
ui/app.zod.ts:10	Base Navigation Item Schema	documents BaseNavItemSchema (line 295)
ui/component.zod.ts:213	Empty Properties Schema	documents the EmptyProps factory
ui/page.zod.ts:22	Page Region Schema	documents PageRegionSchema (line 42)
shared/mapping.zod.ts:6	Base Field Mapping Protocol	genuine module header — its own text says "This module provides the canonical field mapping schema used across ObjectStack"
system/cache.zod.ts:6	Application-Level Cache Protocol	genuine module header — its own text says "Application Cache (system/cache.zod.ts) - This File"

So 8 published reference pages, and 8 pointer rows in the published skill indexes, still open with one schema's comment.

Why no cleverer detector fixes this

The two genuine headers and the eight symbol docs are structurally identical: block inside the import list, a comment between the block and the next declaration. Every positional signal was measured and separates nothing —

• Line number: system/cache and shared/mapping both start at line 6; so do four of the repaired sources and data/hook.
• Imports before the block: 2 for both genuine headers; 2 for data/hook, 5 for ai/agent, 14 for ui/action.
• Block length: system/cache is 24 lines, ui/action is 34.
• Whether the next declaration has its own JSDoc: true for both genuine headers and for six of the eight.

Only the prose differs. A first-sentence pattern check is the approach file-description.ts's own header rejects, with the measurement behind the rejection.

The two routes, both of which need a decision this card does not make

1. An explicit @module marker, scoped to the ambiguous position. Select a block sitting inside the import list only when it carries @module. Cost is a one-line edit on the 2 genuine headers, not on the ~180 sources a corpus-wide marker requirement would touch, and it makes the whole class impossible rather than smaller. It does edit packages/spec/src/**/*.zod.ts, which the [finding] A doc block written for a RE-EXPORTED symbol still becomes the module description — 29 spec modules select a block sitting inside their import list #13263 dispatch fenced off.
2. A corpus pass over the 8. Move each injected import up into the import block, or write a real module header. This also repairs editor hover, which is broken today for every one of the eight: the doc block is attached to the import, so hovering PageRegionSchema shows nothing. That makes it a source defect in its own right, independent of the docs generator.

They compose — 1 is the gate, 2 is the corpus — and 宁可缺, 不要错 argues 1 should land first, since without it the eight pages keep lying whenever a source drifts back.

⛔ Not a re-opening of #13263: that card's fix is landed and its own corpus limb keeps the decidable class closed.