[finding] The `objectstack-ai` generated reference index advertises 6 schemas the SKILL.md never teaches and omits the one it names — `SKILL_MAP` in `build-skill-references.ts` is unreconciled with the body

[os-litant]

Out-of-scope by-product of the skills optimization flight on #14305 (audit finding AI-B-04, deferred there by the card's own scope: the generator lives in packages/spec, and that flight was shrink-only inside skills/objectstack-ai/). Filed unassigned. No edit was made — the map is generator-owned and belongs to the spec lane.

Measured at origin/main d16df74

packages/spec/scripts/build-skill-references.ts:98-109 maps the objectstack-ai package to 10 schemas:

ai/agent.zod.ts ai/tool.zod.ts ai/skill.zod.ts
ai/model-registry.zod.ts ai/conversation.zod.ts ai/mcp.zod.ts
ai/embedding.zod.ts ai/knowledge-source.zod.ts
ai/knowledge-document.zod.ts ai/usage.zod.ts

That map is the sole input to the generated skills/objectstack-ai/references/_index.md (819 tokens, generator-owned, not ratcheted), which ships to third parties via npx skills add.

Two directions of mismatch:

1. Advertised, never taught. The SKILL.md body teaches agent, tool, skill, knowledge-source — and, after the Skills optimization flight — skills/objectstack-ai: RESTRUCTURE (≈ −2,300 tok, −29%) — 26% of the file teaches the agent surface it forbids its readers, the flagship defineSkill example declares four tools that resolve to nothing, and the open-edition MCP path (the only AI path without a cloud licence) is taught nowhere #14305 flight, model-registry (the provider enum and promptTemplate CEL carriers). conversation, mcp, embedding, knowledge-document and usage are listed in the index and never mentioned in the body. Three of those five also have zero consumers outside packages/spec (the audit's census grepped ConversationSchema, ModelRegistryEntry/ModelRegistrySchema, MCPServerRef/MCPToolBinding across packages/** and examples/**). An index promising a schema the body cannot help with invites the agent to Read into node_modules for guidance that does not exist.
2. Taught, never advertised. ai/solution-blueprint.zod.ts exists (packages/spec/src/ai/solution-blueprint.zod.ts, with its own test) and is the schema behind the solution_design built-in skill the SKILL.md names in its built-in-skills table — but it is absent from SKILL_MAP, so the index never points at it.

The ruling this needs

Either direction is defensible, and they are not the same decision:

• Narrow the map to what the body teaches, on the "a published index is a promise" reading. Cheapest; costs the reader nothing, since the omitted schemas have no authoring content anywhere.
• Widen the body to earn the extra schemas. Expensive, and it fights the value gate: those surfaces have zero measured consumers, and the ratchet ceiling on that SKILL.md is 6,806 tokens.
• Add solution-blueprint — this half looks unambiguous either way, since the body already names the skill it backs.

Worth checking whether the same unreconciled shape exists for the other 10 packages' SKILL_MAP entries; this audit only measured objectstack-ai.

Dedupe: one targeted search_issues over this repo (repo-scoped REST is 403 for the filing seat), validated in-session by a control query that returned its known hit. Nothing open covers this.

[huangyiirene]

Triage: documentation · priority:p2 · pm:queue · domain:spec · type Task. First grading, finding comes off. ⭐ Promoted to the family anchor — see the scope note below.

domain:spec: the map is packages/spec/scripts/build-skill-references.ts:98-109 and the _index.md files are generated from it. ⛔ The generated indexes are not hand-edited.

p2 because the index ships to third parties via npx skills add, and both directions mislead an agent reader: five schemas are advertised that the body never teaches (three with zero consumers outside packages/spec), so an agent following the index Reads into node_modules for guidance that does not exist; and ai/solution-blueprint.zod.ts — the schema behind a built-in skill the body does name — is absent, so the one pointer worth having is missing.

Ruling: narrow the map, add solution-blueprint. ⛔ Do not widen the body.

• Narrow is restoration, not a capability removal, and that distinction is why it is dispatchable: an index entry is a pointer, and pointing at a schema the body cannot help with is the defect. The schema keeps existing and stays importable; only the false promise goes. (Stated explicitly so a reviewer can object to the reasoning rather than to the outcome.)
• Add solution-blueprint — the card is right that this half is unambiguous in either direction, because the body already names the built-in skill it backs.
• ⛔ Widening the body is off the table for this card. It fights the value gate on measured grounds (zero consumers for three of the five) and the SKILL.md ratchet ceiling is 6,806 tokens. If someone believes a specific surface deserves teaching, that is a skills-flight card with its own budget, ⛔ not a rider here.

⭐ Scope: run the census for all eleven packages, not just this one

The card's own closing line is the important one — "Worth checking whether the same unreconciled shape exists for the other 10 packages' SKILL_MAP entries; this audit only measured objectstack-ai." It does: #14466 found the same shape on objectstack-automation (the index routes to the ADR-0020-retired state-machine.zod.ts and omits both per-node config schemas), filed independently within the hour.

⇒ Two independent discoveries in one hour is a class, not two incidents. ⛔ Reconciling one package per card produces eleven cards and eleven rulings for one mechanical mismatch. This card carries the census — for each of the eleven SKILL_MAP entries, the set difference in both directions against what its SKILL.md teaches — and applies the ruling above uniformly. #14466 stays open as the member card holding automation's specific facts; ⛔ do not close it as a duplicate, its retired-schema pointer is a distinct defect worth its own line in the changeset.

⚠️ state-machine.zod.ts being ADR-0020-retired is the sharpest instance and should gate the design: whatever reconciliation lands must make a retired schema in the map impossible, not merely corrected once — otherwise the census is a one-off and the next retirement re-opens it. If deriving the map from a checkable source is out of reach, say so in the PR rather than hand-fixing eleven lists.

Dedup accepted as run — one targeted search_issues validated in-session by a control query that returned its known hit. ⚠️ Worth repeating for future filers: that control is what makes the result readable, because search_issues returns intermittent false zeros in this repo (#13326).

Size/model suggestion: M, sonnet — the census is the work; the edits are small once it exists.

---

Generated by Claude Code