Out-of-scope by-product of the SKILL_MAP family PR anchored on #14462, found while adding ai/solution-blueprint.zod.ts to SKILL_MAP['objectstack-ai'] (the addition #14462's triage ruled unambiguous). No edit was made — the repair is in a .zod.ts source, which that card's ruling puts off limits. Filed unassigned.
Measured at origin/main 9c1bcda3
The file opens, after its imports, with a real module header:
/**
* Solution Blueprint Schema (ADR-0033 §4 — plan-first authoring)
*
* The structured-output target an AI agent emits for a *high-level* goal
* ("build me a project-management system") instead of transcribing a field
* list. It is a **simplified proposal shape** ...
*/
const SNAKE_CASE = /^[a-z_][a-z0-9_]*$/;
findModuleDocBlock() (packages/spec/scripts/lib/file-description.ts) requires, as its third condition, that the block document nothing — and "immediately followed by a declaration" counts blank lines only. One blank line separates that header from const SNAKE_CASE, so the block reads as SNAKE_CASE's documentation and is rejected as the module header.
The generators therefore fall through to the export-list fallback. The row now published in skills/objectstack-ai/references/_index.md is:
- `node_modules/@objectstack/spec/src/ai/solution-blueprint.zod.ts` — Exports: BlueprintConditionSchema, BlueprintSummaryOperationsSchema, BlueprintFieldSchema, BlueprintObjectSchema, BlueprintViewSchema
Why it matters
Same class as #14441 (landed as PR #14737) one file over: the fallback line states a true fact about the file and says nothing about its subject, while the sentence that WOULD say it — plan-first authoring, the apply_blueprint expansion — is sitting in the file unused. The skill tells an agent to read the source for exact field shapes, and this is the row routing it there.
Note the shape differs from #14441's: there the wrong block was published, here the right block is suppressed and a machine-generated list takes its place. Both are the header-zone selector deciding against a header a human wrote.
Suggested repair (not a ruling)
Separate the header from SNAKE_CASE by something the selector reads as the end of a preamble — the existing rule already treats a banner comment or a second doc block that way — or give SNAKE_CASE its own one-line doc. Then gen:skill-refs and gen:docs. Adding a pin like packages/spec/scripts/query-pointer-row.test.ts (the #14441 fix's) is the cheap half; the generators cannot see this class themselves, since they reproduce the selector faithfully.
Dedupe: one targeted search_issues over this repo (repo-scoped REST is 403 for this seat), validated in-session by a control query that returned its four known hits. The seven results are all closed and none covers this file.
Out-of-scope by-product of the
SKILL_MAPfamily PR anchored on #14462, found while addingai/solution-blueprint.zod.tstoSKILL_MAP['objectstack-ai'](the addition #14462's triage ruled unambiguous). No edit was made — the repair is in a.zod.tssource, which that card's ruling puts off limits. Filed unassigned.Measured at
origin/main9c1bcda3The file opens, after its imports, with a real module header:
findModuleDocBlock()(packages/spec/scripts/lib/file-description.ts) requires, as its third condition, that the block document nothing — and "immediately followed by a declaration" counts blank lines only. One blank line separates that header fromconst SNAKE_CASE, so the block reads asSNAKE_CASE's documentation and is rejected as the module header.The generators therefore fall through to the export-list fallback. The row now published in
skills/objectstack-ai/references/_index.mdis:Why it matters
Same class as #14441 (landed as PR #14737) one file over: the fallback line states a true fact about the file and says nothing about its subject, while the sentence that WOULD say it — plan-first authoring, the
apply_blueprintexpansion — is sitting in the file unused. The skill tells an agent to read the source for exact field shapes, and this is the row routing it there.Note the shape differs from #14441's: there the wrong block was published, here the right block is suppressed and a machine-generated list takes its place. Both are the header-zone selector deciding against a header a human wrote.
Suggested repair (not a ruling)
Separate the header from
SNAKE_CASEby something the selector reads as the end of a preamble — the existing rule already treats a banner comment or a second doc block that way — or giveSNAKE_CASEits own one-line doc. Thengen:skill-refsandgen:docs. Adding a pin likepackages/spec/scripts/query-pointer-row.test.ts(the #14441 fix's) is the cheap half; the generators cannot see this class themselves, since they reproduce the selector faithfully.Dedupe: one targeted
search_issuesover this repo (repo-scoped REST is 403 for this seat), validated in-session by a control query that returned its four known hits. The seven results are all closed and none covers this file.