baldart 4.66.1 → 4.66.2

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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`).

package/VERSION

@@ -1 +1 @@
-4.66.1
+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

@@ -91,6 +91,12 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    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
@@ -98,7 +104,8 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    ```
    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}"
+     --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
@@ -107,6 +114,12 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    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.
    - `patterns/.gitkeep` — empty dir for future pattern docs.

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

@@ -135,19 +135,71 @@ function arg(name, def = '') {
   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>]');
+    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) {
@@ -158,7 +210,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     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 };
+  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

@@ -115,6 +115,15 @@ and `baldart doctor` treat an unparseable HEAD as drift to repair (re-run
 **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/package.json

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