baldart 4.66.0 → 4.66.2

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.66.2] - 2026-06-23
+
+**`token_bindings` are now validated against the real DTCG vocabulary — fixing dangling bindings found on a real upgrade.** After the v4.66.1 HEAD-serialization fix, a real `/design-system-init` upgrade still produced 26/586 `token_bindings` that didn't resolve in `.tokens.json` (`font.weight.medium` instead of `typography.fontWeight.medium`, `z.overlay` vs `zIndex.overlay`, `space.2` vs `space.sm`, …). Root cause: the agentic enricher (`doc-reviewer`) writes `token_bindings` as free text and guesses plausible-but-wrong names. A dangling binding id is `DS_TOKENS_DRIFT`. This closes the gap so it cannot be written, and instructs the enricher to pick from the actual token vocabulary.
+
+**PATCH** — refines the v4.65.0/v4.66.1 layer; no config/install change.
+
+### Fixed
+
+- **Deterministic binding vocabulary guard** — `serialize-spec.mjs` gains `--tokens <.tokens.json>`: it flattens the DTCG to its real id set and **drops + reports** any `token_bindings` id that does not resolve (the `droppedBindings` count + the dropped list on stderr) — so a dangling binding can never be serialized. Exposed as `tokenIds()` + `validateBindings()`. Proven: `z.overlay`/`font.weight.medium` dropped, `zIndex.overlay`/`typography.fontWeight.medium`/`color.surface` kept.
+- **Prevention at the source** — `/design-system-init` step 4 + `doc-reviewer` (HEAD owner) + `component-manifest-schema.md` now require `token_bindings` to be chosen from the real `${paths.design_tokens}` id list (exact ids, never invented names). The serializer invocation passes `--tokens ${paths.design_tokens}` so the guard runs every generation.
+
+## [4.66.1] - 2026-06-23
+
+**The component-manifest HEAD is now serialized DETERMINISTICALLY — fixing invalid-YAML HEADs found on a real `/design-system-init` upgrade.** A real upgrade run produced 74 per-component specs but **73/74 frontmatter HEADs failed to parse as YAML** — the v4.65.0 skill let the model hand-write the HEAD, so it emitted `props:{}` / `variants:[]` (no space after the colon) and unquoted/multiline `purpose`/`a11y` strings (embedded `:`, quotes, newlines). The HEADs were unparseable → "frontmatter-first" discovery silently fell back → the machine-readable benefit was lost. Same run also wired the DTCG token output to **overwrite a hand-authored `tokens.ts`** (semantic exports `uiTokens`/`categoryPalette` replaced by a generic `export const tokens` — would break every import). This release closes the model-in-the-loop-for-a-deterministic-artifact gap (the recurring lesson behind `setup-worktree.sh` / `merge-worktree.sh`).
+
+**PATCH** — bugfix to the v4.65.0 layer; no new config key, no install change. Schema-change propagation rule does not apply.
+
+### Fixed
+
+- **Deterministic HEAD serializer** — new `framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs` (pure Node, zero-dep): the model supplies field **data** (deterministic JSON ∪ agentic JSON), the script emits valid YAML (every string scalar via `JSON.stringify` = a valid YAML double-quoted scalar; empty collections `{}`/`[]`; block lists; flow-map props) **and the thin INDEX router**, then **self-validates every HEAD and fails closed** (never writes an unparseable HEAD). Proven on the exact DrilldownHeader content that previously failed (backticks, colons, quotes, newline in `purpose`) → parses clean. `/design-system-init` now routes all spec writes through it and **salvages** agentic values from existing malformed HEADs before re-serializing; the spec template marks the HEAD serializer-owned.
+- **Token-output clobber guard (ENFORCED)** — `/design-system-init` must run an **export-preservation check** before pointing `design_tokens.outputs` at an existing token file: the output path may be a hand-authored file only if every existing `export` is reproduced; otherwise it writes to a NEW path and leaves the hand-authored SSOT untouched. The deferred "don't clobber in place" guard from v4.65.0 is now mandatory, not advisory. The config note must state the real direction (`.tokens.json` → output), never the reverse.
+- **Invalid-HEAD detection (safety net)** — `baldart doctor` now parse-checks a sample of spec HEADs (not just "is there a `---`") and the `ds-manifest-nudge` reports `N/M sampled HEADs invalid YAML → re-run /design-system-init`; the `ds-drift` routine + `code-reviewer`/`doc-reviewer`/`component-manifest-schema.md` treat an unparseable HEAD as `DS_COMPONENT_STALE` drift. This is the check that would have caught the bug at ship time.
+
 ## [4.66.0] - 2026-06-23
 
 **Server-side reviewer death is no longer a silent drop in the `/new` review workflows — from a real `new-final-review` run where `qa-sentinel` died on `API Error: 529 Overloaded`.** When a reviewer agent inside `new-final-review.js` / `new-card-review.js` was killed by a transient server-side error (529 Overloaded, 429, 5xx, rate-limit — the org-level limit is SHARED across every terminal/session), the worker pool's `try/catch → null` + `.filter(Boolean)` **silently discarded it**. For `qa-sentinel` this was worst: a dead gate-runner produced an **empty `gateTable`**, which the fan-in read as "no mechanical gates ran ⇒ nothing to block" — so the batch's lint/tsc/test/build/i18n merge gate was lost without any FAIL signal. The two workflows had NO transient retry and NO degraded-coverage signal at all; the canonical handling already existed in `new2.js` (`agentSafe` + `noteDegraded`) and in the prose SSOT (`references/team-mode.md` § transient-vs-genuine) but had **never been propagated** to the other two workflows.

package/VERSION

@@ -1 +1 @@
-4.66.0
+4.66.2

package/framework/.claude/agents/doc-reviewer.md

@@ -67,7 +67,11 @@ documentation scope.
 `token_bindings`, `related`, `must_rules`, `last_verified`. You curate these —
 you do NOT hand-write the deterministic half (`name`/`source`/`source_sha`/
 `props`/`variants`/`composes`), which is regenerated from source by the extractor.
-Never clobber a filled agentic field on a refresh. (This is the design-system twin
+Never clobber a filled agentic field on a refresh. **Pick `token_bindings` from
+the REAL DTCG vocabulary** — read the id list from `${paths.design_tokens}` and
+use exact ids (`typography.fontWeight.medium`, `zIndex.overlay`, `space.sm`),
+never invented names (`font.weight.medium`, `z.overlay`, `space.2`); the
+serializer drops unresolved ids as drift. (This is the design-system twin
 of your i18n-registry ownership: you curate context, tooling fills the mechanical part.)
 
 Standard drift checks against this corpus:

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -85,27 +85,43 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    imports), `category` (import-fan-in heuristic). **This half runs with NO
    subagent** — it is the Codex-portable path. Empty results on a non-TS stack are
    acceptable (advisory), never a failure.
-4. **Enrich — AGENTIC.** Launch `doc-reviewer` to fill the agentic HEAD fields
-   (`purpose`, `a11y`, `token_bindings`, `related`, `must_rules`) — in UPGRADE
-   mode by lifting them from the existing prose body; in GREENFIELD by reading the
-   source. Never clobber a filled agentic field on re-run. Under Codex (no
-   subagents) this degrades to leaving those fields empty + a TODO note.
-5. **Bootstrap the DTCG token SSOT.** See § Token SSOT bootstrap below: derive
-   `.tokens.json` from the existing token source, write `paths.design_tokens`,
-   configure `design_tokens.outputs`, run `baldart tokens build`, and
-   **round-trip verify** (regenerate, diff vs original; surface a non-empty
-   semantic diff, never auto-accept).
-6. **Write the files** under the target path:
-   - `INDEX.md` — **thin generated router**: one row per primitive
-     (`name | source | one-line purpose | spec link`). No Authority Matrix here
-     (it lives in `design-system-protocol.md`). Regenerated from the specs; never
-     hand-edited.
+4. **Enrich — AGENTIC, AS DATA (never hand-write YAML).** Launch `doc-reviewer`
+   to produce the agentic fields (`purpose`, `a11y`, `token_bindings`, `related`,
+   `must_rules`) **as JSON values**, NOT as text typed into a `.md`. In UPGRADE
+   mode, lift them from each spec's existing prose / **salvage** them from the
+   current HEAD even if it is malformed. Never clobber a filled agentic field on
+   re-run. Under Codex (no subagents) this degrades to empty fields + a TODO note.
+   **`token_bindings` MUST be chosen from the REAL token vocabulary** — read the
+   id list from `${paths.design_tokens}` (the DTCG `.tokens.json`) and pick exact
+   ids (`typography.fontWeight.medium`, `zIndex.overlay`, `space.sm`), never
+   invent plausible-but-wrong names (`font.weight.medium`, `z.overlay`, `space.2`).
+   The serializer's `--tokens` guard (step 6) drops any unknown id, but picking
+   correctly here avoids losing real intent.
+5. **Bootstrap the DTCG token SSOT.** See § Token SSOT bootstrap below.
+6. **Write the files — DETERMINISTICALLY (the HEAD is NEVER model-authored).**
+   Merge the deterministic JSON (step 3) with the agentic JSON (step 4) per
+   component into a bundle and run the serializer:
+   ```
+   node .framework/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs \
+     --bundle <bundle.json> --out-dir ${paths.design_system}/components \
+     --index ${paths.design_system}/INDEX.md --brand "${identity.brand_name}" \
+     --tokens ${paths.design_tokens}
+   ```
+   It emits every `components/<Name>.md` (valid-YAML HEAD via deterministic
+   serialization + preserved prose) **and** the thin INDEX router, then
+   **self-validates** every HEAD and **exits non-zero if any fails to parse**
+   (fail-closed — never leave an unparseable HEAD). This is the fix for the
+   model-hand-written-YAML bug class (`props:{}` without a space, unquoted/multiline
+   `purpose`/`a11y`): the model supplies field *data*, the script owns the YAML.
+   Do NOT write the HEAD by hand or via the prose template.
+   `--tokens` (when `paths.design_tokens` is set) activates the **binding
+   vocabulary guard**: any `token_bindings` id that does not resolve in the DTCG
+   `.tokens.json` is DROPPED and REPORTED (the `droppedBindings` count + the list
+   on stderr) — so a `DS_TOKENS_DRIFT` can never be written. Review the dropped
+   list: a drop means doc-reviewer guessed a name that isn't a real token (fix the
+   enrichment or add the token), per step 4.
    - `tokens-reference.md` — **generated** human view of `.tokens.json` (or pure
      narrative). Not a third source of values.
-   - `components/<Name>.md` — one per primitive from
-     `scripts/component-spec.template.md`: the frontmatter HEAD (deterministic +
-     agentic) + prose body. In UPGRADE mode, prepend/refresh the HEAD on existing
-     specs in place, preserving the prose.
    - `patterns/.gitkeep` — empty dir for future pattern docs.
 7. **Update config.** Set `features.has_design_system: true`,
    `paths.design_system: <target>`, and (when tokens bootstrapped)
@@ -136,9 +152,11 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 4. **Token SSOT bootstrap** — § Token SSOT bootstrap (derive `.tokens.json`,
    set outputs, `baldart tokens build`, round-trip verify).
 
-5. **Write files** — per-component HEAD+prose from
-   `scripts/component-spec.template.md`; thin INDEX router; generated
-   tokens-reference; `patterns/.gitkeep`. UPGRADE refreshes HEADs in place.
+5. **Write files DETERMINISTICALLY** — merge deterministic+agentic field data per
+   component and run `scripts/serialize-spec.mjs` (emits valid-YAML HEADs +
+   thin INDEX router, self-validates, fails closed). Never hand-write the HEAD.
+   Then the generated tokens-reference + `patterns/.gitkeep`. UPGRADE salvages
+   agentic values from existing (even malformed) HEADs before re-serializing.
 
 6. **Persist config** — `features.has_design_system: true`, `paths.design_system`,
    and (if tokens bootstrapped) `paths.design_tokens` + `design_tokens.outputs`.
@@ -168,20 +186,27 @@ Tailwind theme) but no DTCG source, bootstrap the SSOT:
    `{color.gray.200}`?) to `doc-reviewer` for `$type` assignment + alias
    reconstruction. Write it to `paths.design_tokens` (default
    `${paths.design_system}/tokens.tokens.json` or `src/ui/tokens.tokens.json`).
-2. **Configure outputs.** Set `design_tokens.outputs` to regenerate the EXISTING
-   token file in place (e.g. `{ format: ts, path: src/ui/tokens.ts }`) so there is
-   exactly one token artifact and it becomes generated.
+2. **Configure outputs — NEVER clobber a hand-authored token file (ENFORCED).**
+   Before pointing `design_tokens.outputs` at an existing token file, run the
+   **export-preservation check**: generate to a TEMP path and compare the set of
+   `export`ed names (and value count) against the current file. The output path
+   may be the existing file **only if** every existing export is reproduced
+   (byte/format diff allowed; missing/renamed exports NOT). Otherwise — the common
+   case for a hand-authored token file that exports several named, semantically
+   structured objects (which the generic `export const tokens` shape does NOT
+   reproduce) — write to a **NEW path** (e.g. `tokens.generated.ts`) and leave the
+   hand-authored file untouched. The user flips the import site when ready.
+   **A mismatched in-place output is the footgun this guard exists to prevent**:
+   `baldart tokens build` (and the `doctor`/`ds-drift` backfills) would otherwise
+   silently overwrite the hand-authored SSOT and break every import.
 3. **Build + round-trip verify.** Run `baldart tokens build`, then diff the
    regenerated output against the original. **A non-empty semantic diff (values
-   changed/dropped) is surfaced to the user, never auto-accepted** — it means the
-   `.tokens.json` derivation lost something. Only a formatting-only diff is safe.
-4. **Mark generated.** The output carries `// baldart-generated from .tokens.json`
-   — from now on, edit `.tokens.json`, never the output (the DS_TOKENS_DRIFT gate
-   enforces this).
-
-**Do NOT replace a hand-authored token file in place on the first run** unless the
-round-trip is clean — prefer generating to a new path and let the user flip the
-import site once they trust it (the in-place replacement is the deferred step).
+   changed/dropped, or exports missing) is surfaced and never auto-accepted.**
+4. **Mark generated + record direction honestly.** The output carries
+   `// baldart-generated from .tokens.json`. The config note MUST state the real
+   direction (`.tokens.json` → output via `baldart tokens build`), never the
+   reverse — a note that says "edit tokens.ts, regenerate .tokens.json" contradicts
+   the pipeline and misleads the user. From now on edit `.tokens.json` only.
 
 ## INDEX.md template (thin generated router)
 
@@ -244,7 +269,8 @@ hardcode literals that duplicate these tokens.
 - `framework/agents/project-context.md` — config + overlay contract.
 - `framework/.claude/skills/ui-design/SKILL.md` — primary consumer (reads
   the registry BLOCKING).
-- `scripts/component-spec.template.md` — per-component spec template (HEAD + prose).
+- `scripts/component-spec.template.md` — prose-body reference (HEAD is serializer-owned).
 - `scripts/extract-manifest.mjs` — deterministic, zero-dep HEAD extractor (Codex-portable).
+- `scripts/serialize-spec.mjs` — deterministic HEAD serializer (valid-YAML, fail-closed) + INDEX router emitter.
 - `framework/agents/component-manifest-schema.md` — the frontmatter HEAD schema.
 - `framework/docs/COMPONENT-MANIFEST-LAYER.md` — layer design + lifecycle.

package/framework/.claude/skills/design-system-init/scripts/component-spec.template.md

@@ -1,3 +1,8 @@
+<!-- NOTE: the frontmatter HEAD below is EMITTED DETERMINISTICALLY by
+     scripts/serialize-spec.mjs (field data in, valid YAML out). Do NOT hand-write
+     or hand-fill it — invalid YAML (e.g. `props:{}` without a space, unquoted
+     multiline strings) is exactly the bug the serializer prevents. This template
+     documents the SHAPE + is the reference for the PROSE BODY below the fences. -->
 ---
 # Machine-readable HEAD — schema: framework/agents/component-manifest-schema.md
 # DETERMINISTIC fields (regenerated from source — do not hand-curate):

package/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// Deterministic component-spec serializer (since v4.66.1).
+//
+// Pure Node, ZERO dependencies. This is the fix for the class of bug where the
+// frontmatter HEAD was hand-written (by a model) and came out as INVALID YAML
+// (`props:{}` without a space, unquoted/multiline `purpose`/`a11y` strings, …),
+// which defeated the whole machine-readable point. The HEAD MUST be emitted by
+// THIS serializer, never typed by a model.
+//
+// Key trick for zero-dep validity: `JSON.stringify(s)` is always a valid YAML
+// double-quoted scalar (YAML double-quoted strings are a superset of JSON string
+// escaping), so every string scalar / list item is JSON.stringify'd. Empty
+// collections use flow `{}` / `[]`; non-empty arrays use block lists; `props`
+// uses a flow map per entry. The output is deterministic (source order).
+//
+// Usage:
+//   node serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>]
+//   bundle.json = { brand?, components: [ { name, source, source_sha, status,
+//     category, props:{}, variants:[], composes:[], purpose, token_bindings:[],
+//     a11y, related:[], must_rules:[], last_verified, owner, prose } ] }
+// Exits non-zero if any emitted HEAD fails to re-parse (when js-yaml is present).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const SAFE = /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/; // plain-scalar-safe (no quoting needed)
+const RESERVED = new Set(['true', 'false', 'null', 'yes', 'no', 'on', 'off', '~']);
+
+/** A YAML-safe scalar: plain when obviously safe, else a JSON double-quoted string. */
+function scalar(v) {
+  if (v === null || v === undefined) return '""';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  if (s !== '' && SAFE.test(s) && !RESERVED.has(s.toLowerCase()) && !/^\d{4}-\d{2}-\d{2}/.test(s)) return s;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return s; // a bare date is fine
+  return JSON.stringify(s); // valid YAML double-quoted scalar (handles quotes/colons/newlines)
+}
+
+/** Block list (or flow [] when empty) for an array of string items. */
+function list(key, arr, indent = '') {
+  if (!Array.isArray(arr) || arr.length === 0) return `${indent}${key}: []`;
+  const lines = arr.map((it) => `${indent}  - ${scalar(it)}`);
+  return `${indent}${key}:\n${lines.join('\n')}`;
+}
+
+/** props: nested flow map per entry (or flow {} when empty). */
+function propsBlock(props) {
+  const keys = props && typeof props === 'object' ? Object.keys(props) : [];
+  if (keys.length === 0) return 'props: {}';
+  const lines = keys.map((k) => {
+    const p = props[k] || {};
+    const parts = [`type: ${scalar(p.type ?? '')}`, `required: ${p.required ? 'true' : 'false'}`];
+    if (p.default !== undefined && p.default !== null && p.default !== '') parts.push(`default: ${scalar(p.default)}`);
+    // The map KEY (prop name) may be non-identifier (rare) — quote if needed.
+    const key = SAFE.test(k) ? k : JSON.stringify(k);
+    return `  ${key}: { ${parts.join(', ')} }`;
+  });
+  return `props:\n${lines.join('\n')}`;
+}
+
+/** Emit the full frontmatter HEAD body (between the --- fences) for one component. */
+export function emitHead(c) {
+  const L = [];
+  L.push('# Machine-readable HEAD — schema: framework/agents/component-manifest-schema.md');
+  L.push('# DETERMINISTIC (regenerated from source — do not hand-edit):');
+  L.push(`name: ${scalar(c.name)}`);
+  L.push(`source: ${scalar(c.source)}`);
+  L.push(`source_sha: ${scalar(c.source_sha ?? '')}`);
+  L.push(`status: ${scalar(c.status || 'stable')}`);
+  L.push(`category: ${scalar(c.category || 'primitive')}`);
+  L.push(propsBlock(c.props));
+  L.push(list('variants', c.variants));
+  L.push(list('composes', c.composes));
+  L.push('# AGENTIC (curated by doc-reviewer — preserved across regeneration):');
+  L.push(`purpose: ${scalar(c.purpose ?? '')}`);
+  L.push(list('token_bindings', c.token_bindings));
+  L.push(`a11y: ${scalar(c.a11y ?? '')}`);
+  L.push(list('related', c.related));
+  L.push(list('must_rules', c.must_rules));
+  L.push(`last_verified: ${scalar(c.last_verified || TODAY)}`);
+  L.push(`owner: ${scalar(c.owner || 'doc-reviewer')}`);
+  return L.join('\n');
+}
+
+// Date is fine in a CLI script (this is not a resumable workflow).
+const TODAY = new Date().toISOString().slice(0, 10);
+
+/** Full spec file = HEAD fences + preserved prose body. */
+export function emitSpec(c) {
+  const prose = (c.prose && c.prose.trim()) ? c.prose.replace(/^\s+/, '') : `# ${c.name}\n\n> Per-component spec. The HEAD above is the machine-readable contract.\n`;
+  return `---\n${emitHead(c)}\n---\n\n${prose.replace(/\s*$/, '')}\n`;
+}
+
+/** Thin INDEX router from the component set. */
+export function emitIndex(components, brand = 'Project') {
+  const rows = components
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => `| ${c.name} | ${c.source} | ${(c.purpose || '').replace(/\|/g, '\\|').slice(0, 80)} | [components/${c.name}.md](components/${c.name}.md) |`);
+  return [
+    '<!-- baldart-generated router — regenerated from components/*.md HEAD. Do not hand-edit. -->',
+    '---',
+    'title: "UI Components Index"',
+    'canonicality: canonical',
+    'owner: doc-reviewer',
+    'routing_scope: ui-components',
+    'baldart_generated: true',
+    '---',
+    '',
+    `# ${brand} Design System — Component Router`,
+    '',
+    'Discovery entry point. Read a row\'s spec HEAD (not the source) to reuse a primitive.',
+    'Authority Matrix + token contract: framework/agents/design-system-protocol.md.',
+    '',
+    '| Component | Source | Purpose | Spec |',
+    '|-----------|--------|---------|------|',
+    ...rows,
+    '',
+  ].join('\n');
+}
+
+/** Optional strict re-parse (only when js-yaml is resolvable). */
+function tryValidate(headBody) {
+  let yaml;
+  try { yaml = require('js-yaml'); } catch (_) { return { checked: false }; }
+  try { yaml.load(headBody); return { checked: true, ok: true }; }
+  catch (e) { return { checked: true, ok: false, error: e.message.split('\n')[0] }; }
+}
+
+function arg(name, def = '') {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
+}
+
+/** Flatten a DTCG `.tokens.json` tree to the set of dot-path token ids. */
+export function tokenIds(dtcg) {
+  const ids = new Set();
+  (function walk(node, prefix) {
+    if (!node || typeof node !== 'object') return;
+    if (Object.prototype.hasOwnProperty.call(node, '$value')) { ids.add(prefix); return; }
+    for (const k of Object.keys(node)) {
+      if (k.startsWith('$')) continue;
+      walk(node[k], prefix ? `${prefix}.${k}` : k);
+    }
+  })(dtcg, '');
+  return ids;
+}
+
+/**
+ * Drop `token_bindings` ids that don't resolve in the DTCG vocabulary. The
+ * agentic enricher (doc-reviewer) writes bindings as free text and can guess
+ * names that don't exist (`font.*` vs `typography.*`, `z.*` vs `zIndex.*`); a
+ * dangling id is DS_TOKENS_DRIFT. This is the deterministic guard: keep only
+ * real ids, return what was dropped so it is SURFACED (never silently lost).
+ */
+export function validateBindings(components, idSet) {
+  const dropped = [];
+  for (const c of components) {
+    const kept = [];
+    for (const id of c.token_bindings || []) {
+      if (idSet.has(id)) kept.push(id);
+      else dropped.push({ component: c.name, id });
+    }
+    c.token_bindings = [...new Set(kept)];
+  }
+  return dropped;
+}
+
+// CLI
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const bundlePath = arg('--bundle');
+  const outDir = arg('--out-dir');
+  const indexPath = arg('--index');
+  const brandArg = arg('--brand');
+  const tokensPath = arg('--tokens'); // optional DTCG .tokens.json → binding vocab guard
+  if (!bundlePath || !outDir) {
+    console.error('usage: serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>] [--tokens <.tokens.json>]');
+    process.exit(2);
+  }
+  const bundle = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
+  const components = bundle.components || [];
+  const brand = brandArg || bundle.brand || 'Project';
+
+  // Token-binding vocabulary guard (since v4.66.2): drop ids absent from the DTCG.
+  let dropped = [];
+  if (tokensPath) {
+    try {
+      const ids = tokenIds(JSON.parse(fs.readFileSync(tokensPath, 'utf8')));
+      dropped = validateBindings(components, ids);
+      if (dropped.length) {
+        console.error(`token_bindings: dropped ${dropped.length} id(s) not in ${path.basename(tokensPath)} (DS_TOKENS_DRIFT avoided):`);
+        for (const d of dropped.slice(0, 20)) console.error(`  - ${d.component}: ${d.id}`);
+        if (dropped.length > 20) console.error(`  … +${dropped.length - 20} more`);
+      }
+    } catch (e) {
+      console.error(`token vocab guard skipped: cannot read ${tokensPath} (${e.message.split('\n')[0]})`);
+    }
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  let invalid = 0;
+  for (const c of components) {
+    const spec = emitSpec(c);
+    fs.writeFileSync(path.join(outDir, `${c.name}.md`), spec, 'utf8');
+    const head = spec.match(/^---\n([\s\S]*?)\n---/)[1];
+    const v = tryValidate(head);
+    if (v.checked && !v.ok) { invalid++; console.error(`INVALID HEAD ${c.name}.md: ${v.error}`); }
+  }
+  if (indexPath) fs.writeFileSync(indexPath, emitIndex(components, brand), 'utf8');
+  const report = { schema: 'baldart.serialize-spec/1', written: components.length, index: !!indexPath, invalid, droppedBindings: dropped.length };
+  console.log(JSON.stringify(report));
+  if (invalid > 0) process.exit(1); // fail-closed: never leave invalid HEADs
+}

package/framework/agents/component-manifest-schema.md

@@ -97,6 +97,33 @@ NO human-curated judgment (the Authority Matrix moved to
 `design-system-protocol.md`; per-component detail lives in each spec). Because it
 is generated, it is always safe to regenerate from the specs — never hand-edit it.
 
+## Serialization contract (HARD — the HEAD is never model-authored)
+
+The frontmatter HEAD MUST be emitted by the deterministic serializer
+(`framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs`), which
+takes the fields as **data** (deterministic JSON ∪ agentic JSON) and writes valid
+YAML. A model (doc-reviewer / ui-expert) supplies the agentic field **values**,
+never types YAML into the `.md`. Rationale: hand-written HEADs produced invalid
+YAML at scale (`props:{}` missing the space after the colon; unquoted/multiline
+`purpose`/`a11y` strings with embedded `:` / quotes / newlines), which made the
+whole HEAD unparseable and defeated the machine-readable purpose.
+
+**Validity invariant:** every HEAD MUST parse as YAML. The serializer self-checks
+and fails closed (never writes an unparseable HEAD); `code-reviewer`, `ds-drift`,
+and `baldart doctor` treat an unparseable HEAD as drift to repair (re-run
+`/design-system-init`). When refreshing an existing spec whose HEAD is malformed,
+**salvage** the agentic values leniently, then re-serialize — never strict-parse
+and lose them.
+
+**Token-binding vocabulary invariant:** every `token_bindings` id MUST resolve to
+a real node in the DTCG `.tokens.json` (`paths.design_tokens`). The agentic
+enricher picks ids from that file's actual vocabulary — never invents
+plausible-but-wrong names (`font.weight.medium`/`z.overlay`/`space.2` instead of
+`typography.fontWeight.medium`/`zIndex.overlay`/`space.sm`). The serializer's
+`--tokens` guard DROPS + REPORTS any unresolved id (so a `DS_TOKENS_DRIFT` is
+never written); a dropped id means the enricher guessed wrong (fix it or add the
+token).
+
 ## Regeneration contract
 
 - **Anchor**: `source_sha`. A regeneration run skips a component whose source is

package/framework/routines/ds-drift.routine.yml

@@ -17,13 +17,16 @@ prompt: |
   1. **INDEX coverage**: the `${paths.design_system}/INDEX.md` router must list
      every primitive that has a spec. Flag `DS_INDEX_DRIFT` for any mismatch
      (fix by regenerating the router, never hand-editing it).
-  2. **Per-component HEAD accuracy**: for each
-     `${paths.design_system}/components/<Name>.md`, compare its frontmatter HEAD
-     against the source — `source_sha` vs the current git blob, `props`/`variants`
-     vs the TS types (schema: `framework/agents/component-manifest-schema.md`).
-     Flag `DS_COMPONENT_STALE` when `source_sha` is stale (or >7 days unverified
-     with a source change). A prose-only spec with no HEAD is an upgrade candidate
-     (recommend `/design-system-init`), NOT itself stale.
+  2. **Per-component HEAD accuracy + validity**: for each
+     `${paths.design_system}/components/<Name>.md`, first verify the frontmatter
+     HEAD **parses as YAML** — an unparseable HEAD (e.g. `props:{}` without a
+     space, unquoted multiline strings) is `DS_COMPONENT_STALE`; fix by re-running
+     `/design-system-init` (which re-serializes deterministically), never by hand.
+     Then compare the HEAD against the source — `source_sha` vs the current git
+     blob, `props`/`variants` vs the TS types (schema:
+     `framework/agents/component-manifest-schema.md`). Flag `DS_COMPONENT_STALE`
+     when `source_sha` is stale (or >7 days unverified with a source change). A
+     prose-only spec with no HEAD is an upgrade candidate, NOT itself stale.
   3. **Animations reconciliation**: `${paths.design_system}/patterns/animations.md`
      must match keyframes in the project's global styles. Flag
      `DS_ANIMATIONS_DRIFT`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.66.0",
+  "version": "4.66.2",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/doctor.js

@@ -501,14 +501,24 @@ async function detectState(cwd, opts = {}) {
             state.dsManifestNudge = true;
             state.dsManifestReason = 'no per-component specs found';
           } else {
-            // Cheap sample: does ANY spec carry a frontmatter HEAD (starts with `---`)?
-            const structured = specs.slice(0, 8).some((f) => {
-              try { return fs.readFileSync(path.join(compDir, f), 'utf8').startsWith('---'); }
-              catch (_) { return false; }
-            });
-            if (!structured) {
+            // Sample up to 8 specs. Two failure modes: (a) prose-only (no HEAD),
+            // (b) HEAD present but INVALID YAML (the model-hand-written bug class).
+            const sample = specs.slice(0, 8);
+            let withHead = 0, headParseFail = 0;
+            for (const f of sample) {
+              let t = '';
+              try { t = fs.readFileSync(path.join(compDir, f), 'utf8'); } catch (_) { continue; }
+              const m = t.match(/^---\n([\s\S]*?)\n---/);
+              if (!m) continue;
+              withHead++;
+              try { yaml.load(m[1]); } catch (_) { headParseFail++; }
+            }
+            if (withHead === 0) {
               state.dsManifestNudge = true;
               state.dsManifestReason = 'specs are prose-only (no machine-readable HEAD)';
+            } else if (headParseFail > 0) {
+              state.dsManifestNudge = true;
+              state.dsManifestReason = `${headParseFail}/${withHead} sampled spec HEADs are invalid YAML — re-run /design-system-init to re-serialize`;
             }
           }
         }