[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

[os-project-manager]

Observation-class finding, surfaced while landing the view name-grammar note (PR #13262). Filed unassigned; not fixed there — that PR's ruling authorized a family-level note on one module, not a sweep.

The residual hole in the module-description selection rule

packages/spec/scripts/lib/file-description.ts decides which doc block of a *.zod.ts module becomes the prose its reference page opens with. Its rule, quoted from its own header, is three conditions: top-level, in the header zone, and documenting nothing — where "documenting nothing" means the block is not immediately followed by a declaration, and imports / re-exports explicitly do not count as declarations (MODULE_PLUMBING), because this repo writes module headers on either side of them.

That third condition is the load-bearing one, and its own justification is TSDoc's rule read back: a doc block belongs to the declaration it immediately precedes. But a doc block immediately preceding an import or export { … } line also belongs to something — the symbol being imported or re-exported. The rule cannot tell those two apart, so a comment written about a re-exported symbol is published as the page's subject.

Measured instance, confirmed end to end: packages/spec/src/ui/view.zod.ts carried this block at line 18, directly above import { HttpMethodSubsetSchema, HttpRequestSchema } from '../shared/http.zod';

HTTP Method Enum & HTTP Request Schema
Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.

content/docs/references/ui/view.mdx — a page documenting ~50 view schemas — opened with exactly that, and gen:skill-refs copied its first line into two published skill indexes, so skills/objectstack-data/references/_index.md and skills/objectstack-ui/references/_index.md each described ui/view.zod.ts as "HTTP Method Enum & HTTP Request Schema". PR #13262 corrects that one module by giving it a real module description; it does not touch the rule or the other modules.

Scale

Reimplementing the selection rule and running it over packages/spec/src/*/*.zod.ts on origin/main at 7404925:

bucket	count
sources scanned	193
block selected, sits above a real declaration boundary (ordinary module header)	105
block selected, sits directly above an import / re-export line	69
no qualifying block — page prints no description	19

The 69 are not 69 defects: most are genuine module headers deliberately written above the import block, which is the spelling MODULE_PLUMBING exists to permit. The suspicious subset is the one where the block sits inside the import list rather than at the top of the file — 29 of the 69 begin after line 5, and 22 of those 29 open with a title-case symbol name, the signature of a comment written for the symbol on the next line:

ui/action.zod.ts:27         "Action Parameter Schema"
ui/app.zod.ts:10            "Base Navigation Item Schema"
ui/component.zod.ts:213     "Empty Properties Schema"
ui/dashboard.zod.ts:28      "Color variant for dashboard widgets (e.g., KPI cards)."
ui/page.zod.ts:22           "Page Region Schema"
ui/report.zod.ts:11         "Report Type Enum"
data/field.zod.ts:35        "Field Type Enum"
data/object.zod.ts:9        "API Operations Enum"
api/discovery.zod.ts:10     "Service Status Enum"
shared/metadata-types.zod.ts:16  " Supported metadata file formats"
…

Each of those is one published reference page whose opening paragraph may be one schema's doc rather than the module's — the same shape file-description.ts's header records as already-fixed ("Transport Protocol Enum (one enum's doc, on a page documenting fourteen schemas)"), reached through the one door the rule still leaves open. The count is a candidate list, not a verdict: each needs reading before it is called wrong, because a short title-case line can legitimately be a module header too.

Why it is worth recording

The blast radius is larger than a docs page. gen:skill-refs takes the block's first line as the pointer-row description in the published skill bundles, so a misattributed block ships to customer projects, not only to the docs site. And the failure is invisible to check:docs and check:skill-refs by construction: both compare the artifact to the source, and the artifact faithfully reproduces whatever block the rule selected — which is precisely the argument file-description.ts makes for why the selection rule, not a detector, had to be the gate.

Candidate directions (not a recommendation — this needs a spec-seat call)

1. Tighten the rule: treat a block whose next non-blank line is an import / re-export as documenting that, unless it is the file's first block (position before any import). Cheap, mechanical, and it would have caught view.zod.ts; it would also demote the ~40 legitimate headers written above the imports, so it needs the "first block" carve-out measured rather than assumed.
2. Require an explicit marker (@module <category>/<name>, which 10 sources already use) and select only a marked block. Loud and unambiguous; costs a one-line edit on ~180 sources.
3. Triage the 29 by hand and give each a real module header, leaving the rule alone — the same remedy the earlier "write real module headers" pass took, applied to the subclass it did not cover.

No option is free of the others' cost, and which one is right depends on whether the rule or the corpus is judged to be the thing that is wrong.

[os-project-manager]

Triage (R+26) — graded pm:queue · priority:p1 · type Bug. domain:spec was already correct (packages/spec/scripts/**) and is kept.

p1 — and the reason is the blast radius, not the count. This does not stop at the docs site: gen:skill-refs takes the selected block's first line as the pointer-row description in the published skill bundles, so a misattributed block ships to customer projects. The measured instance had skills/objectstack-data/references/_index.md and skills/objectstack-ui/references/_index.md both describing ui/view.zod.ts — a module of ~50 view schemas — as "HTTP Method Enum & HTTP Request Schema".

⭐ Under this project's standing principle that the published skill bundles are the platform's largest outward-facing asset and are judged whole-package, a defect that corrupts their index rows is not documentation debt. That is what carries it to p1 rather than the 29.

Type Bug: the module-description rule publishes one symbol's doc as the module's subject. ⚠️ And the card's sharpest point is that this is invisible to check:docs and check:skill-refs by construction — both compare artifact to source, and the artifact faithfully reproduces whatever block the rule chose. ⇒ no gate can ever go red about it, which is exactly the argument file-description.ts's own header makes for why the selection rule had to be the gate.

⛔ Scope — read the 29 BEFORE choosing among the three directions

The card is explicit and triage is making it the fence:

The count is a candidate list, not a verdict: each needs reading before it is called wrong, because a short title-case line can legitimately be a module header too.

and closes with:

which one is right depends on whether the rule or the corpus is judged to be the thing that is wrong.

⇒ that judgement is not available until the 29 are read. So the deliverable is ordered:

1. Read the 29 (of which 22 open with a title-case symbol name) and record, per module, whether the selected block is a misattributed symbol doc or a legitimate module header written above the imports.
2. Only then choose among tighten-the-rule / require-an-explicit-marker / hand-triage — the reading supplies the number that decides it.

⛔ Do not start by tightening the rule. Direction 1 would also demote the ~40 legitimate headers deliberately written above the import block — the spelling MODULE_PLUMBING exists to permit — and the card says its "first block" carve-out needs measuring rather than assuming. Shipping it unmeasured trades 29 wrong pages for ~40 newly-blank ones.

⚠️ 69 is not the defect count and must not be reported as one. 69 = block sits above an import/re-export; 29 = of those, begins after line 5; 22 = of those, opens with a title-case symbol name. Only the last is even suspicious. ⛔ Do not let the 69 become the headline.

Escalation boundary: choosing the mechanism is a spec-seat call, ⛔ not the maintainer's inbox — it moves no product semantics and no public contract shape, and the escalation threshold's own escape hatch applies (an existing rule, file-description.ts's stated three conditions, frames the decision). ⚠️ But if the chosen route is direction 2, a one-line edit across ~180 sources is a large mechanical sweep and its own dispatch — report the scope before starting it rather than absorbing it.

Provenance: PR #13262 fixed the view.zod.ts instance under a ruling that authorised a family-level note on one module, not a sweep. ⇒ that fence was honoured and this card is where the sweep question properly lives. ⛔ Do not reopen #13262.

---

Generated by Claude Code