fix(spec): regenerate drifted skill references + react-blocks contract, and gate them in CI (#3138)

skills/*/references/_index.md and the objectstack-ui react-blocks contract are
generated from packages/spec/src and committed, but nothing regenerated them in
CI — no workflow referenced either generator, the spec `build` script does not
run them, and neither had a `check:` mode. They drifted. Unlike the reference
docs (#3134), these ship to third parties via `npx skills add`, so the drift is
served straight to consumers' agents.

An independent oracle over the committed indexes: 6 of 113 schema pointers named
files that no longer exist — automation/workflow.zod.ts (deleted by #1398),
system/masking.zod.ts (deleted), data/dataset.zod.ts (renamed to data/seed.zod.ts
by #1620). After this change: 126 pointers, 0 broken.

Regenerating alone was not enough. SKILL_MAP still named data/dataset.zod.ts, and
the generator warned-and-skipped on the missing file, so a plain regen would have
quietly dropped seed coverage from objectstack-data — whose own SKILL.md
advertises defineSeed() authoring — and the new gate would then have locked that
in as correct. Point the map at data/seed.zod.ts and make a dangling entry a hard
failure in both modes.

Gate mechanics follow build-docs.ts (#3134): every write goes through emit(),
every wholesale-regenerated folder through manageDir(), nothing touches disk
until flush() — so write and --check share all generation logic and differ only
in disposition. Extracted to scripts/lib/generated-output.ts. manageDir() takes
an ownership predicate because a skill's references/ folder is only partially
generated: _index.md is ours, but react-blocks.md (sibling generator) and
hand-written notes must survive.

Placed in lint.yml's "TypeScript Type Check" (no paths filter + required), not
ci.yml's check-generated: that job's filter lists specific spec paths but no
schema dirs, so a PR touching src/data/** or src/ui/** never triggers it, and it
is not required either. Both gates need no build, so they run before the
workspace build and fail in seconds.

Each gate was proven to go red before being trusted (13/13): stale content,
missing file, stale untracked leftover, dangling SKILL_MAP entry, missing skill
dir, and a spec change the contract had not absorbed. The stale-leftover case is
why manageDir exists — git diff --exit-code returns 0 on it.

Follow-up: #3139 (import regex is blind to multi-line imports).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.github/workflows/lint.yml

@@ -144,6 +144,29 @@ jobs:
       - name: Check generated reference docs are in sync with the spec
         run: pnpm --filter @objectstack/spec check:docs
 
+      # Same class, same reasoning, different surface: skills/*/references/_index.md
+      # and the objectstack-ui react-blocks contract are generated from
+      # packages/spec/src and committed, and nothing regenerated them either. These
+      # ship to third parties via `npx skills add objectstack-ai/framework`, so the
+      # drift is served straight to consumers' agents — 6 of 113 schema pointers named
+      # files the spec had already deleted or renamed.
+      #
+      # Not in ci.yml's `check-generated` job for the reason above: its `generated`
+      # filter lists specific spec paths (migrations/, conversions/, protocol-version)
+      # but no schema dirs, so a PR touching src/data/** or src/ui/** — exactly what
+      # drives these two artifacts — never triggers it. It is not required, either.
+      #
+      # Both read packages/spec/src via tsx and need no build (verified with every
+      # workspace dist/ removed), so they run before the workspace build. check:skill-refs
+      # additionally fails on a SKILL_MAP entry naming a file the spec no longer has:
+      # that silent skip is what let the map keep pointing at data/dataset.zod.ts for a
+      # year after #1620 renamed it to data/seed.zod.ts.
+      - name: Check generated skill references are in sync with the spec
+        run: pnpm --filter @objectstack/spec check:skill-refs
+
+      - name: Check the react-blocks contract is in sync with the spec
+        run: pnpm --filter @objectstack/spec check:react-blocks
+
       # Example apps are AI-authoring reference templates; a red typecheck is a
       # bad signal to copy from. tsup transpiles them without a full typecheck,
       # so build alone will not catch type drift — typecheck them explicitly.

packages/spec/package.json

@@ -190,6 +190,7 @@
     "gen:docs": "tsx scripts/build-docs.ts",
     "check:docs": "pnpm gen:schema && tsx scripts/build-docs.ts --check",
     "gen:skill-refs": "tsx scripts/build-skill-references.ts",
+    "check:skill-refs": "tsx scripts/build-skill-references.ts --check",
     "gen:skill-docs": "tsx scripts/build-skill-docs.ts",
     "check:skill-docs": "tsx scripts/build-skill-docs.ts --check",
     "analyze": "tsx scripts/analyze-bundle-size.ts",
@@ -205,6 +206,7 @@
     "test:coverage": "vitest run --coverage",
     "check:liveness": "tsx scripts/liveness/check-liveness.mts",
     "gen:react-blocks": "tsx scripts/build-react-blocks-contract.ts",
+    "check:react-blocks": "tsx scripts/build-react-blocks-contract.ts --check",
     "check:react-conformance": "tsx scripts/check-react-blocks-conformance.ts"
   },
   "keywords": [

packages/spec/scripts/build-react-blocks-contract.ts

@@ -8,19 +8,24 @@
 //   - skills/objectstack-ui/contracts/react-blocks.contract.json  (machine)
 //   - skills/objectstack-ui/references/react-blocks.md            (AI-facing)
 //
-// Run: pnpm --filter @objectstack/spec gen:react-blocks
+// Run:
+//   pnpm --filter @objectstack/spec gen:react-blocks            # write
+//   pnpm --filter @objectstack/spec check:react-blocks          # verify in sync (CI)
 
 process.env.OS_EAGER_SCHEMAS = '1';
 
-import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
 import { REACT_BLOCKS, type ReactInteractionProp } from '../src/ui/react-blocks';
+import { createSink } from './lib/generated-output';
 
 const REPO = path.resolve(__dirname, '../../..');
 const OUT_JSON = path.join(REPO, 'skills/objectstack-ui/contracts/react-blocks.contract.json');
 const OUT_MD = path.join(REPO, 'skills/objectstack-ui/references/react-blocks.md');
 
+const CHECK = process.argv.includes('--check');
+const { emit, flush } = createSink({ check: CHECK, repoRoot: REPO });
+
 // ---- JSON-schema prop extraction -----------------------------------------
 function resolveRoot(js: any): any {
   // zod v4 may wrap the root in { $ref: '#/$defs/X', $defs: { X: {...} } }.
@@ -100,7 +105,7 @@ const contract = {
   note: "Props each component accepts in kind:'react' page source. Reference blocks by their PascalCase tag. kind: data=declarative config (from the spec schema) · binding=connects to data · controlled=React state · callback=React function. These blocks are for DATA. Live data: const adapter = useAdapter(); adapter.find/findOne/create/update. STYLING (ADR-0065) — a page's source is runtime metadata, so the console's build-time Tailwind NEVER scans it: utility classNAMES silently produce no CSS. Do NOT use Tailwind className in page source. (a) Layout/chrome: inline style={} with hsl(var(--token)) theme colors — e.g. color:'hsl(var(--foreground))', background:'hsl(var(--card))', border:'1px solid hsl(var(--border))', and px/flex for layout. (b) Overlays: render <ObjectForm formType='drawer'|'modal' open onOpenChange> (a pre-styled Sheet/Dialog) — never hand-roll a fixed inset-0 backdrop.",
   blocks,
 };
-fs.writeFileSync(OUT_JSON, JSON.stringify(contract, null, 2) + '\n');
+emit(OUT_JSON, JSON.stringify(contract, null, 2) + '\n');
 
 // markdown
 const esc = (s: string) => String(s).replace(/\|/g, '\\|');
@@ -134,7 +139,30 @@ L.push('## Injected scope (closure variables, reference directly — not props)'
 L.push('');
 L.push('`React` · `useAdapter` · `data` · `variables` · `page`. Kanban/calendar/gantt/timeline/map of an object = `<ListView navigation={…} />` with the matching visualization, or `<Block type="object-kanban" …/>`.');
 L.push('');
-fs.writeFileSync(OUT_MD, L.join('\n'));
+emit(OUT_MD, L.join('\n'));
 
-console.log(`✅ react-blocks contract: ${blocks.length} blocks → ${path.relative(REPO, OUT_JSON)} + ${path.relative(REPO, OUT_MD)}`);
+console.log(`react-blocks contract: ${blocks.length} blocks → ${path.relative(REPO, OUT_JSON)} + ${path.relative(REPO, OUT_MD)}`);
 for (const b of blocks) console.log(`   <${b.tag}> ${b.props.length} props`);
+
+flush({
+  surface: 'skills/objectstack-ui/ react-blocks contract',
+  regenerate: '  pnpm --filter @objectstack/spec gen:react-blocks\n  git add skills/objectstack-ui',
+  guard: () => {
+    // Guard the two ways this generator can emit a plausible-but-empty contract
+    // and have --check compare it against nothing meaningful.
+    if (blocks.length === 0) return 'REACT_BLOCKS is empty — nothing to generate from packages/spec/src/ui/react-blocks.ts.';
+    // `dataProps()` swallows a z.toJSONSchema failure and returns [], so schemas
+    // that fail to load degrade to a contract carrying only the hand-authored
+    // overlay props rather than crashing. Checking `props.length` would miss it
+    // (the overlay is still there) — the data props are what vanish.
+    const specBacked = blocks.filter((b) => b.specSchema);
+    const withData = specBacked.filter((b) => b.props.some((p) => p.kind === 'data'));
+    if (specBacked.length > 0 && withData.length === 0) {
+      return (
+        `All ${specBacked.length} spec-backed blocks resolved 0 data props — the spec schemas failed to load\n` +
+        `  (z.toJSONSchema errors are swallowed in dataProps()), so this is the overlay alone, not a real contract.`
+      );
+    }
+    return null;
+  },
+});

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

@@ -18,11 +18,14 @@
  * 3. Writes `skills/{name}/references/_index.md` with pointers + one-line
  *    descriptions extracted from each file's leading JSDoc comment
  *
- * Usage: tsx scripts/build-skill-references.ts
+ * Usage:
+ *   tsx scripts/build-skill-references.ts            # write
+ *   tsx scripts/build-skill-references.ts --check    # verify in sync (CI); exit 1 on drift
  */
 
 import fs from 'fs';
 import path from 'path';
+import { createSink, type Owns } from './lib/generated-output';
 
 // ── Paths ────────────────────────────────────────────────────────────────────
 
@@ -31,6 +34,9 @@ const SPEC_SRC = path.resolve(__dirname, '../src');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
 const SPEC_PKG = '@objectstack/spec';
 
+const CHECK = process.argv.includes('--check');
+const { emit, manageDir, flush } = createSink({ check: CHECK, repoRoot: REPO_ROOT });
+
 // ── Skill → Zod file mapping ────────────────────────────────────────────────
 // Paths are relative to packages/spec/src/ (category/file.zod.ts)
 
@@ -41,7 +47,7 @@ const SKILL_MAP: Record<string, string[]> = {
     'data/validation.zod.ts',
     'data/hook.zod.ts',
     'data/datasource.zod.ts',
-    'data/dataset.zod.ts',
+    'data/seed.zod.ts',
     'security/permission.zod.ts',
   ],
   'objectstack-query': [
@@ -94,7 +100,7 @@ const SKILL_MAP: Record<string, string[]> = {
     // project setup (was objectstack-quickstart)
     'kernel/manifest.zod.ts',
     'data/datasource.zod.ts',
-    'data/dataset.zod.ts',
+    'data/seed.zod.ts',
     // plugin development (was objectstack-plugin)
     'kernel/plugin.zod.ts',
     'kernel/context.zod.ts',
@@ -130,23 +136,34 @@ function extractLocalImports(filePath: string): string[] {
   return imports;
 }
 
-function resolveAll(entryFiles: string[]): string[] {
+/**
+ * Transitive closure of a skill's core files.
+ *
+ * Only SKILL_MAP entries can be `missing` — `extractLocalImports` resolves
+ * against disk, so a dep that doesn't exist is never queued. A dangling entry
+ * is therefore an authoring bug in SKILL_MAP, not a spec change to absorb, and
+ * the caller fails on it: silently dropping the pointer is how the skill ends
+ * up advertising a schema it no longer references (`data/dataset.zod.ts`
+ * lingered here for a year after #1620 renamed it to `data/seed.zod.ts`).
+ */
+function resolveAll(entryFiles: string[]): { files: string[]; missing: string[] } {
   const visited = new Set<string>();
+  const missing: string[] = [];
   const queue = [...entryFiles];
   while (queue.length > 0) {
     const rel = queue.shift()!;
     if (visited.has(rel)) continue;
     const abs = path.resolve(SPEC_SRC, rel);
     if (!fs.existsSync(abs)) {
-      console.warn(`  ⚠ File not found: ${rel} (skipped)`);
+      missing.push(rel);
       continue;
     }
     visited.add(rel);
     for (const dep of extractLocalImports(abs)) {
       if (!visited.has(dep)) queue.push(dep);
     }
   }
-  return [...visited].sort();
+  return { files: [...visited].sort(), missing };
 }
 
 // ── JSDoc description extractor ──────────────────────────────────────────────
@@ -226,57 +243,73 @@ function generateIndex(skillName: string, coreFiles: string[], allFiles: string[
   return lines.join('\n');
 }
 
-// ── Cleanup helper ───────────────────────────────────────────────────────────
+// ── Managed scope ────────────────────────────────────────────────────────────
 
-function cleanReferencesDir(refsDir: string) {
-  if (!fs.existsSync(refsDir)) {
-    fs.mkdirSync(refsDir, { recursive: true });
-    return;
-  }
-  for (const entry of fs.readdirSync(refsDir)) {
-    // Keep hand-written markdown other than _index.md untouched.
-    if (entry === '_index.md') {
-      fs.rmSync(path.resolve(refsDir, entry));
-      continue;
-    }
-    const entryPath = path.resolve(refsDir, entry);
-    const stat = fs.statSync(entryPath);
-    if (stat.isDirectory()) {
-      fs.rmSync(entryPath, { recursive: true });
-    } else if (entry.endsWith('.zod.ts')) {
-      fs.rmSync(entryPath);
-    }
-  }
+/**
+ * Which paths under a skill's `references/` folder this generator owns — i.e.
+ * would delete and rewrite on a real run, and must therefore flag as stale
+ * under `--check`.
+ *
+ * The folder is only *partially* ours: `react-blocks.md` is written by
+ * build-react-blocks-contract.ts and hand-written notes are allowed, so both
+ * are left alone. Subfolders and loose `*.zod.ts` are leftovers from the
+ * retired bundled-schema layout (skills used to carry copies of the schemas);
+ * we still sweep them so an old checkout converges.
+ */
+function ownsReferenceEntry(refsDir: string): Owns {
+  return (abs) => {
+    const rel = path.relative(refsDir, abs);
+    if (!rel || rel.startsWith('..')) return false;
+    if (rel.includes(path.sep)) return true; // inside a subfolder → wiped wholesale
+    return rel === '_index.md' || rel.endsWith('.zod.ts');
+  };
 }
 
 // ── Main ─────────────────────────────────────────────────────────────────────
 
 function main() {
   console.log('🔗 Building skill schema reference indexes...\n');
+  const problems: string[] = [];
   let totalSkills = 0;
 
   for (const [skillName, coreFiles] of Object.entries(SKILL_MAP)) {
     const skillDir = path.resolve(SKILLS_DIR, skillName);
     if (!fs.existsSync(skillDir)) {
-      console.warn(`⚠ Skill directory not found: ${skillName}, skipping`);
+      problems.push(`${skillName} → no such skill directory under skills/`);
       continue;
     }
 
     console.log(`📦 ${skillName}`);
-    const allFiles = resolveAll(coreFiles);
+    const { files: allFiles, missing } = resolveAll(coreFiles);
+    for (const m of missing) problems.push(`${skillName} → ${m} (no such file under packages/spec/src)`);
     console.log(`   ${coreFiles.length} core + ${allFiles.length - coreFiles.length} deps`);
 
     const refsDir = path.resolve(skillDir, 'references');
-    cleanReferencesDir(refsDir);
-
-    fs.writeFileSync(
-      path.resolve(refsDir, '_index.md'),
-      generateIndex(skillName, coreFiles, allFiles),
-    );
+    manageDir(refsDir, ownsReferenceEntry(refsDir));
+    emit(path.resolve(refsDir, '_index.md'), generateIndex(skillName, coreFiles, allFiles));
     totalSkills += 1;
   }
 
-  console.log(`\n✅ Done — ${totalSkills} skill index files written`);
+  flush({
+    surface: 'skills/*/references/_index.md',
+    regenerate: '  pnpm --filter @objectstack/spec gen:skill-refs\n  git add skills',
+    guard: () => {
+      // A dangling SKILL_MAP entry drops a schema pointer from a shipped skill.
+      // Dropping it quietly is what this generator used to do; fail instead, in
+      // both modes — the map is authored config, so this is always a bug in it.
+      if (problems.length) {
+        return (
+          `SKILL_MAP is out of sync with packages/spec/src:\n\n` +
+          problems.map((p) => `  - ${p}`).join('\n') +
+          `\n\n  Fix the mapping in ${path.relative(REPO_ROOT, __filename)} — point it at the\n` +
+          `  schema's current path, or drop the entry if the concept is gone.`
+        );
+      }
+      // Nothing emitted means nothing compared; "no drift" would read as green.
+      if (totalSkills === 0) return `No skills found under ${path.relative(REPO_ROOT, SKILLS_DIR)} — nothing to generate.`;
+      return null;
+    },
+  });
 }
 
 main();