baldart 4.66.1 → 4.67.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.67.0] - 2026-06-23
+
+**Token-binding CORRECTNESS check + PRD-Inventory-sourced enrichment — the survivor of an adversarial pass that killed a design-time "intent seed".** Goal: capture design intent ("when/how/which-tokens") so the implementing agent doesn't reverse-engineer the manifest's agentic fields from code. The proposed `component-intent.yml` seed (emitted by `/prd`) was refuted 3/3 — it duplicates the PRD's existing UI Element Inventory + the manifest (twin), goes stale via `/prd-add` REDO, survives-but-wrong (the v4.66.2 guard checks token EXISTENCE, not correctness-for-this-component), and as an on-disk prose file would be skipped/unowned/Codex-inert. This ships the deterministic survivors instead.
+
+**MINOR** — adds a capability (usage check + intent-source wiring); no new config key, no install change. Schema-change propagation rule does NOT apply.
+
+### Added
+
+- **Token-binding correctness check (`serialize-spec.mjs --verify-usage`)** — closes the half v4.66.2 left open (existence ≠ correctness): a binding can exist in the DTCG yet be wrong for this component. `verifyBindingUsage(components, cwd)` (exported) reads each component's effective styling surface — its own `source` (+ sibling `.module.css`/`.css`) **plus the sources of the primitives it directly `composes`** (a wrapper presenting an overlay via a composed Popover legitimately binds `zIndex.overlay`) — and reports any `token_bindings` id absent from that surface as `unverifiedBindings`. **ADVISORY, never a drop/block** (a binding can be legitimately indirect — Tailwind classes, a non-sibling stylesheet — so a hard block would false-fire). Resolves source from the `source` field, never a guessed path. Validated on mayo: 96% of 603 bindings verified; the residual surfaces for review, exit 0.
+
+### Changed
+
+- **Intent-sourced enrichment (no new artifact)** — `doc-reviewer` + `/design-system-init` step 4 now fill the agentic HEAD fields (`purpose`/`a11y`/`must_rules`) from the PRD's existing **UI Element Inventory** (`Purpose`/`function_ref`/`Behavior`/`States`) when the component traces to a PRD (card `links.prd`/`links.design`), reconciled against the implemented source — capturing design-time intent instead of reverse-engineering it. Clean fallback to source-only when no PRD exists. `token_bindings` are now picked preferring ids the source actually uses.
+- **Advisory propagated to the three Post-Intervention sites** — `design-system-protocol.md` (check 3), `code-reviewer.md` (Rule 8), and the `ds-drift` routine now flag a resolves-but-unused binding as a `DS_TOKENS_DRIFT` **advisory** (review-required: fix or justify as indirect), distinct from the hard existence drift. SSOT'd in `component-manifest-schema.md` (existence = HARD/drop; usage = ADVISORY/report). `/design-system-init` passes `--verify-usage` on every generation.
+
+## [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.67.0

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

@@ -58,7 +58,11 @@ Concrete enforcement contract for the review pass:
 2. For any component in the diff, cross-check against its
    `components/<Name>.md` HEAD — variants, props, `token_bindings`, a11y,
    `must_rules`. A `token_bindings` ID that does not resolve in the DTCG source
-   (`paths.design_tokens`) is `DS_TOKENS_DRIFT`.
+   (`paths.design_tokens`) is `DS_TOKENS_DRIFT` (hard). A `token_bindings` ID that
+   resolves but is NOT used in the component's effective styling surface (own
+   source + directly-composed children) is a `DS_TOKENS_DRIFT` **advisory** (flag
+   for review — the binding is likely over-attributed or wrong; not a merge-block,
+   since it can be legitimately indirect).
 3. Enforce design-system MUST rules (the spec HEAD's `must_rules` + project INDEX)
    as HIGH-confidence findings. Typical rules include:
    - No hardcoded hex, shadow, radius, spacing literals — only tokens. When

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

@@ -67,7 +67,24 @@ 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 (existence) and **flags ids not used in the
+component's source** (correctness, advisory) — so prefer the ids the source
+actually consumes.
+
+**Intent source order (when the component traces to a PRD/design).** Do NOT
+reverse-engineer intent from code alone when a richer source exists. If the work
+traces to a PRD (the card's `links.prd` / `links.design`), read that PRD's **UI
+Element Inventory** row for this component (its `Purpose`, `function_ref`,
+`Behavior`, `States`) and use it as the **primary source** for `purpose` /
+`a11y` / `must_rules` — it captures the design-time intent ("when/how to use")
+that the implemented code does not encode. Then **reconcile against the
+implemented source** (the deterministic fields + actual token usage are ground
+truth; the Inventory is intent, not API). Fallback: when there is no PRD/Inventory
+for the component, infer from the source as before. (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,19 @@ 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`).
+   Prefer the ids the component's **source actually uses** — the serializer's
+   `--tokens` guard (step 6) drops unknown ids and `--verify-usage` flags ids not
+   used in the source as advisory drift; picking from real usage avoids both.
+   **Intent source order:** if the component traces to a PRD (a card's
+   `links.prd` / `links.design`), read that PRD's **UI Element Inventory** row
+   (`Purpose`/`function_ref`/`Behavior`/`States`) as the PRIMARY source for
+   `purpose`/`a11y`/`must_rules` (design-time intent the code does not encode),
+   then reconcile against the implemented source. Fallback to source-only when no
+   PRD/Inventory exists.
 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 +111,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} --verify-usage
    ```
    It emits every `components/<Name>.md` (valid-YAML HEAD via deterministic
    serialization + preserved prose) **and** the thin INDEX router, then
@@ -107,6 +121,16 @@ 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** (existence): any `token_bindings` id that does not resolve
+   in the DTCG `.tokens.json` is DROPPED and REPORTED (`droppedBindings`) — so a
+   `DS_TOKENS_DRIFT` can never be written. `--verify-usage` activates the
+   **correctness check**: ids that resolve but are NOT used in the component's
+   styling surface (own source + composed children) are REPORTED (not dropped) as
+   `unverifiedBindings` — an advisory review list (the binding is over-attributed
+   or wrong, OR legitimately indirect via Tailwind/non-sibling CSS). Review both
+   lists per step 4: a drop = a guessed-wrong name; an unverified id = pick the id
+   the source actually uses, or justify it.
    - `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,130 @@ 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;
+}
+
+/**
+ * Correctness check (since v4.67.0): a `token_bindings` id should actually be
+ * USED in the component's OWN source. The v4.66.2 guard only checks the id
+ * EXISTS in the DTCG — a plausible-but-wrong binding (exists globally, not used
+ * here) survives it. This reads each component's real source (`source` field +
+ * sibling `.module.css`/`.css`) and marks a binding "found" if its CSS-var form
+ * (`--<dot-as-dash>`) or the dotted id appears.
+ *
+ * ADVISORY, never a drop/block: a binding can be legitimately indirect
+ * (Tailwind-class-based with no `--var`, or in a non-sibling stylesheet) — so
+ * unverified ids are REPORTED for review (`DS_TOKENS_DRIFT` advisory), not
+ * removed. The component's effective styling surface = its OWN source + the
+ * sources of the primitives it directly `composes` (a wrapper that presents an
+ * overlay via a composed Popover legitimately binds `zIndex.overlay`); only a
+ * binding absent from that whole surface is a genuine phantom. Resolve from the
+ * `source` field (NEVER a guessed `components/<Name>.tsx` path — that
+ * mis-resolves nested components). Returns [{component, id}] for the NOT-found.
+ */
+export function verifyBindingUsage(components, cwd) {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const readSurface = (rel) => {
+    let s = '';
+    for (const p of [rel, rel.replace(/\.tsx?$/, '.module.css'), rel.replace(/\.tsx?$/, '.css')]) {
+      try { s += fs.readFileSync(path.join(cwd, p), 'utf8'); } catch (_) { /* may not exist */ }
+    }
+    return s;
+  };
+  const unverified = [];
+  for (const c of components) {
+    const b = c.token_bindings || [];
+    if (!b.length || !c.source) continue;
+    let src = readSurface(c.source);
+    for (const childName of c.composes || []) {
+      const child = byName.get(childName);
+      if (child && child.source) src += readSurface(child.source);
+    }
+    if (!src) continue; // cannot read any source → cannot judge; stay silent (no false flag)
+    for (const id of b) {
+      const cssVar = `--${id.replace(/\./g, '-')}`;
+      if (!src.includes(cssVar) && !src.includes(id)) unverified.push({ component: c.name, id });
+    }
+  }
+  return unverified;
+}
+
 // 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
+  const verifyUsage = process.argv.includes('--verify-usage'); // advisory source-usage check
+  const cwd = arg('--cwd', process.cwd());
   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>] [--verify-usage] [--cwd <dir>]');
     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]})`);
+    }
+  }
+
+  // Binding correctness check (since v4.67.0): ADVISORY — report bindings not
+  // used in the component's own source (never drop; can be legitimately indirect).
+  let unverified = [];
+  if (verifyUsage) {
+    unverified = verifyBindingUsage(components, cwd);
+    if (unverified.length) {
+      console.error(`token_bindings: ${unverified.length} id(s) not found in their component source (DS_TOKENS_DRIFT advisory — review: fix or justify as indirect):`);
+      for (const u of unverified.slice(0, 20)) console.error(`  - ${u.component}: ${u.id}`);
+      if (unverified.length > 20) console.error(`  … +${unverified.length - 20} more`);
+    }
+  }
+
   fs.mkdirSync(outDir, { recursive: true });
   let invalid = 0;
   for (const c of components) {
@@ -158,7 +269,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, unverifiedBindings: unverified.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,28 @@ 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 (existence — HARD):** 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).
+
+**Token-binding correctness invariant (usage — ADVISORY):** existence is not
+correctness — a token can exist globally yet be wrong for this component. A
+`token_bindings` id SHOULD actually be USED in the component's effective styling
+surface: its own source (`source` + sibling `.module.css`/`.css`) or the source
+of a primitive it directly `composes` (a wrapper presenting an overlay via a
+composed Popover legitimately binds `zIndex.overlay`). The serializer's
+`--verify-usage` check REPORTS — never drops — any id absent from that surface as
+a `DS_TOKENS_DRIFT` **advisory** (review-required), because a binding can be
+legitimately indirect (Tailwind classes, a non-sibling stylesheet). The reviewer
+either corrects the binding or justifies it; it is NOT a hard merge-block (a hard
+block would false-fire). Pick bindings the source actually uses to keep this
+clean.
+
 ## Regeneration contract
 
 - **Anchor**: `source_sha`. A regeneration run skips a component whose source is

package/framework/agents/design-system-protocol.md

@@ -482,8 +482,13 @@ For each item in the diff that touched a visual surface, run these 4 checks:
    set, the change MUST be made in `.tokens.json` and the stack-native output
    regenerated via `baldart tokens build` (a hand-edit to the generated output is
    the drift). Otherwise update the project's token source + reference. Either
-   way, a dangling `token_bindings` ID is drift. Stale = `DS_TOKENS_DRIFT`,
-   task blocked.
+   way, a dangling `token_bindings` ID (not in the DTCG) is drift. Stale =
+   `DS_TOKENS_DRIFT`, task blocked. **Binding correctness (advisory):** a
+   `token_bindings` id that exists in the DTCG but is NOT used in the component's
+   effective styling surface (own source + directly-composed children) is a
+   `DS_TOKENS_DRIFT` **advisory** finding (review-required, NOT a block) — the
+   `serialize-spec.mjs --verify-usage` check reports these; the reviewer corrects
+   the binding or justifies it as legitimately indirect.
 4. **Surfaced silent primitive ⇒ added to INDEX**: during the work, did you
    reuse a primitive that exists in the source tree but is **not** in
    `INDEX.md`? If yes, add it to the INDEX in the same change (or open a

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

@@ -34,7 +34,11 @@ prompt: |
      verify the generated outputs (`design_tokens.outputs`) + `tokens-reference.md`
      equal `baldart tokens build` — a hand-edited generated file or a dangling
      `token_bindings` ID is `DS_TOKENS_DRIFT`. When unset, fall back to verifying
-     the project token source vs `tokens-reference.md`.
+     the project token source vs `tokens-reference.md`. Also run the binding
+     CORRECTNESS check (`serialize-spec.mjs --verify-usage`): a `token_bindings`
+     id not used in its component's styling surface is a `DS_TOKENS_DRIFT`
+     **advisory** — list it for review (fix the binding or justify as indirect),
+     do not auto-remove.
   5. Emit a consolidated report under
      `docs/reports/{{YYYYMMDD}}-ds-drift.md`.
 

package/package.json

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