fix(spec): narrow the objectstack-ai reference index to what its SKILL.md teaches

The published `objectstack-ai` index advertised five schemas the body never
teaches -- `conversation`, `mcp`, `embedding`, `knowledge-document`, `usage`,
three of them with zero consumers outside `packages/spec` -- and omitted
`ai/solution-blueprint.zod.ts`, the schema behind the `solution_design`
built-in skill the body's own table names. An index entry is a POINTER, so
pointing at a schema the body cannot help with sends an agent reading into
`node_modules` for guidance that does not exist. The schemas keep existing and
stay importable; only the false promise leaves.

`embedding` is still published, as a transitive dependency:
`knowledge-source.zod.ts` composes `EmbeddingModelSchema`, so that pointer IS
reachable from the authorable face -- the test the other four fail.

Adds the first map-level guard, in `scripts/lib/` beside `export-list.ts` and
`file-description.ts` because the generator self-executes on import: a core
entry that is not a `*.zod.ts` path emits no pointer row at all today, with no
`missing` row and a green `--check`, because the closure filter drops it
silently before the index template ever sees it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk

Author: claude

packages/spec/scripts/build-skill-references.ts

@@ -28,6 +28,7 @@ import path from 'path';
 import { exportListDescription } from './lib/export-list';
 import { findModuleDocBlock } from './lib/file-description';
 import { createSink, type Owns } from './lib/generated-output';
+import { checkCoreEntryShape } from './lib/skill-map-guards';
 
 // ── Paths ────────────────────────────────────────────────────────────────────
 
@@ -100,12 +101,18 @@ const SKILL_MAP: Record<string, string[]> = {
     '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',
+    // The schema behind the `solution_design` built-in skill the body's
+    // built-in-skills table names. Taught, never advertised until now.
+    'ai/solution-blueprint.zod.ts',
+    // `conversation`, `mcp`, `embedding`, `knowledge-document` and `usage`
+    // left this list: the body teaches none of them, and three had zero
+    // consumers outside packages/spec. An index entry is a POINTER, and
+    // pointing at a schema the body cannot help with is the defect — the
+    // schemas keep existing and stay importable. `embedding` is still
+    // published here as a transitive dep, because `knowledge-source.zod.ts`
+    // composes `EmbeddingModelSchema`: that pointer is reachable from the
+    // authorable face, which is exactly the test the other four fail.
   ],
   'objectstack-api': [
     'api/endpoint.zod.ts',
@@ -359,7 +366,10 @@ function ownsReferenceEntry(refsDir: string): Owns {
 
 function main() {
   console.log('🔗 Building skill schema reference indexes...\n');
-  const problems: string[] = [];
+  // Map-level guards run before any file is read: they ask questions of the
+  // authored config that the artifact-vs-generator comparison structurally
+  // cannot (see lib/skill-map-guards.ts).
+  const problems: string[] = [...checkCoreEntryShape(SKILL_MAP)];
   let totalSkills = 0;
 
   for (const [skillName, coreFiles] of Object.entries(SKILL_MAP)) {

packages/spec/scripts/lib/skill-map-guards.ts

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Guards over the authored `SKILL_MAP` in `build-skill-references.ts`.
+ *
+ * The map is hand-written config that decides what a published skill index
+ * points at, and every defect this file refuses was found by a human reading
+ * a shipped index rather than by a gate: an entry the owning SKILL.md never
+ * teaches, an entry two packages both claim, an entry that emits no row at
+ * all. `check:skill-refs` cannot see any of them — it compares the artifact
+ * against the generator, and the generator reproduces a wrong map faithfully.
+ * So these ask questions of the MAP, before the artifact exists.
+ *
+ * They live here, beside `export-list.ts` and `file-description.ts`, for the
+ * reason those do: the generator self-executes on import, so logic that wants
+ * a unit test cannot live in it.
+ *
+ * ## What these guards deliberately do NOT claim
+ *
+ * None of them decides whether a schema is RETIRED, and no such guard is
+ * shipped, because no checkable source for it exists in this repo — measured,
+ * not assumed:
+ *
+ *  - the ADR-0087 registry (`src/migrations/entries/retired-defs/**`) names
+ *    defs removed at a major version. `automation/state-machine.zod.ts` is not
+ *    there and correctly so: the def still exists and still parses, through
+ *    `AgentSchema.lifecycle`;
+ *  - the file's own header carries the ADR-0020 retirement in prose, and that
+ *    same header documents the door that SURVIVES — so a prose grep flags a
+ *    file that is live surface for another package;
+ *  - the liveness ledger classifies properties, not files.
+ *
+ * The retirement that mattered was PACKAGE-RELATIVE: dead surface for
+ * automation authoring, live surface for AI authoring. Nothing in the tree
+ * expresses a per-package liveness claim, so nothing can derive it. What is
+ * mechanical is below, and what is not stays a human judgement stated out loud
+ * in the map.
+ */
+
+/** A `SKILL_MAP`-shaped value: skill name → its core schema paths. */
+export type SkillCoreMap = Record<string, readonly string[]>;
+
+/**
+ * Every core entry must be a path this generator can actually publish.
+ *
+ * `resolveAll()` keeps only `*.zod.ts` from the closure, because the published
+ * package's `files` allowlist ships those sources and nothing else — a pointer
+ * to any other src file 404s in a consumer's `node_modules`. That filter runs
+ * over the CORE list too, and the index template then intersects the core set
+ * with what survived: so a core entry that is not a `.zod.ts` path is dropped
+ * from the index SILENTLY — no `missing` row, and a green `--check`. The map is
+ * authored config; a line in it that emits nothing is a bug in the map, not a
+ * shape to absorb.
+ */
+export function checkCoreEntryShape(map: SkillCoreMap): string[] {
+  const problems: string[] = [];
+  for (const [skillName, coreFiles] of Object.entries(map)) {
+    for (const rel of coreFiles) {
+      if (rel.endsWith('.zod.ts')) continue;
+      problems.push(
+        `${skillName} → ${rel} is not a *.zod.ts path — only those sources ship in ` +
+          `@objectstack/spec, so this entry emits no pointer row at all. Point it at the ` +
+          `schema file, or drop it.`,
+      );
+    }
+  }
+  return problems;
+}

packages/spec/scripts/skill-map-guards.test.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Negative tests for the `SKILL_MAP` guards in `lib/skill-map-guards.ts`.
+ *
+ * Each guard exists because a shipped skill index was found wrong by a human
+ * reading it, and `check:skill-refs` was green the whole time: that gate
+ * compares the artifact against the generator, so a wrong map produces a
+ * faithful artifact and a green verdict. The guards ask their question of the
+ * MAP instead, and these tests assert they REFUSE — a guard that only ever
+ * returns an empty array is the failure mode a positive-only test cannot see.
+ *
+ * Two legs, failing differently, as `query-pointer-row.test.ts` does one layer
+ * up:
+ *
+ *  - the BEHAVIOUR leg drives each guard over fabricated maps: one that must
+ *    be refused, and one that must pass, so neither an always-green nor an
+ *    always-red guard survives;
+ *  - the WIRING leg reads `build-skill-references.ts` and asserts each guard is
+ *    actually called there. A guard nobody calls is green in this file and
+ *    absent from the gate, which is exactly the state the map was already in.
+ *
+ * The live corpus is deliberately NOT re-asserted here: `check:skill-refs` runs
+ * the real generator over the real map on every CI run, and it fails on any
+ * problem these guards report. Restating that in vitest would buy a second
+ * spelling of one fact, not a second fact.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { checkCoreEntryShape, type SkillCoreMap } from './lib/skill-map-guards';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const GENERATOR = path.resolve(HERE, 'build-skill-references.ts');
+
+describe('checkCoreEntryShape — a core entry that emits no row is refused', () => {
+  it('refuses a non-.zod.ts core entry', () => {
+    const map: SkillCoreMap = {
+      'objectstack-demo': ['data/field.zod.ts', 'contracts/plugin-lifecycle-events.ts'],
+    };
+    const problems = checkCoreEntryShape(map);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('contracts/plugin-lifecycle-events.ts');
+    expect(problems[0]).toContain('objectstack-demo');
+  });
+
+  it('passes a map whose entries are all schema paths', () => {
+    // Without this leg a guard that returned a problem for every entry would
+    // satisfy the refusal test above and break every real run.
+    expect(checkCoreEntryShape({ 'objectstack-demo': ['data/field.zod.ts'] })).toEqual([]);
+  });
+
+  it('names every offending entry, not just the first', () => {
+    const problems = checkCoreEntryShape({
+      a: ['x.ts'],
+      b: ['data/field.zod.ts', 'y.md'],
+    });
+    expect(problems).toHaveLength(2);
+  });
+});
+
+describe('the generator wires the guards in', () => {
+  const source = (): string => fs.readFileSync(GENERATOR, 'utf-8');
+
+  it('reads the generator at all', () => {
+    // Nothing read means nothing asserted, and "no missing call" would read as
+    // green — the failure mode a source-text pin actually has.
+    expect(source().length).toBeGreaterThan(1000);
+  });
+
+  it('calls checkCoreEntryShape on SKILL_MAP', () => {
+    expect(source()).toContain('checkCoreEntryShape(SKILL_MAP)');
+  });
+});

skills/objectstack-ai/references/_index.md

@@ -10,18 +10,15 @@ from `node_modules` — there is no local copy in the skill bundle.
 ## Core schemas
 
 - `node_modules/@objectstack/spec/src/ai/agent.zod.ts` — Exports: AIModelConfigSchema, StructuredOutputFormatSchema, TransformPipelineStepSchema, StructuredOutputConfigSchema, AgentSchema
-- `node_modules/@objectstack/spec/src/ai/conversation.zod.ts` — AI Conversation Memory Protocol
-- `node_modules/@objectstack/spec/src/ai/embedding.zod.ts` — Embedding & Vector Store Primitives
-- `node_modules/@objectstack/spec/src/ai/knowledge-document.zod.ts` — Knowledge Document / Chunk / Hit — canonical shapes shared by every
 - `node_modules/@objectstack/spec/src/ai/knowledge-source.zod.ts` — Knowledge Source — declarative metadata describing what to index and
-- `node_modules/@objectstack/spec/src/ai/mcp.zod.ts` — Model Context Protocol (MCP) — Reference & Binding Primitives
 - `node_modules/@objectstack/spec/src/ai/model-registry.zod.ts` — AI Model Registry Protocol
 - `node_modules/@objectstack/spec/src/ai/skill.zod.ts` — Skill Trigger Condition Schema
+- `node_modules/@objectstack/spec/src/ai/solution-blueprint.zod.ts` — Exports: BlueprintConditionSchema, BlueprintSummaryOperationsSchema, BlueprintFieldSchema, BlueprintObjectSchema, BlueprintViewSchema
 - `node_modules/@objectstack/spec/src/ai/tool.zod.ts` — Exports: ToolSchema
-- `node_modules/@objectstack/spec/src/ai/usage.zod.ts` — AI Usage Primitives
 
 ## Transitive dependencies
 
+- `node_modules/@objectstack/spec/src/ai/embedding.zod.ts` — Embedding & Vector Store Primitives
 - `node_modules/@objectstack/spec/src/automation/state-machine.zod.ts` — XState-inspired State Machine Protocol — hierarchical states, guarded
 - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1).
 - `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema