@verevoir/design-gate 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @verevoir/design-gate
+
+Zero-dependency deterministic verifier for a design pack: DTCG token validation,
+regenerate-diff of generated value views, and value-drift checks over the concept
+docs. Node built-ins only — runs anywhere with no install.
+
+The **same code** the design capabilities emit into a produced pack (for that
+pack's CI) **and** the runtime imports to enforce a capability's
+`verify: design-pack` postcondition (STDIO-451) — one source, two consumers.
+
+## Use
+
+```js
+import { verifyFiles } from '@verevoir/design-gate';
+
+// files: { path -> content } (e.g. read back from the branch the model wrote to)
+const { ok, findings } = verifyFiles({
+  'design-language/tokens/colour.tokens.json': '…',
+  'design-language/tokens/colour.tokens.md': '…',
+  'design-language/colour.md': '…',
+});
+```
+
+`verifyFiles(map)` returns `{ ok, findings }`; each finding is
+`{ kind, file?, where?, message }` (kinds `DTCG` / `VIEW_DRIFT` / `VALUE_DRIFT` /
+`NO_TOKENS` / `PARSE`), model-actionable so an execution loop can re-prompt until
+green. The full surface (`verifyPack`, `renderTokenView`, `validateDtcg`,
+`tokenLiterals`, `findValueDrift`, `runGate`) and the check semantics are in
+[`design/README.md`](design/README.md).

package/design/README.md

@@ -0,0 +1,68 @@
+# Design gate — deterministic token/doc checks
+
+The deterministic half of the design converter. The design capabilities
+(`ingest-style-guide`, `infer-design-system-from-repo`, `generate-design-tokens`,
+`generate-agent-rules`) **emit this tooling into the pack they produce** and wire
+it into that pack's CI, so faithfulness is *enforced* rather than trusted to the
+model's prose discipline. Zero dependencies (Node built-ins only), so a produced
+pack runs it with no install.
+
+It exists because the bar was already in the corpus — `design-system-reference-stays-true`
+says "point at the token source, don't re-type values" — and a model under
+context pressure re-types them anyway. The facts (values, structure) are
+mechanically checkable; this is the checker.
+
+## Checks
+
+- **`dtcg.mjs` — `validateDtcg(tree)`**: the token source is well-formed DTCG. A
+  node is a token *or* a group, not both; a dimension `$value` is a real value,
+  not a CSS expression; every `{alias}` resolves and none cycle; `$schema` is the
+  real published one (`https://tr.designtokens.org/format/`), not a fabricated URL.
+- **`value-drift.mjs` — `tokenLiterals(tree)` + `findValueDrift(literals, doc)`**:
+  no value-free doc re-types a token value. High-signal by design — it matches
+  distinctive literals (hex, unit-bearing dimensions, colour functions) where an
+  occurrence in prose is unambiguously a re-typed value;
+  bare unitless numbers (font weights, type-scale steps) are owned by the
+  generated value views, and fenced code blocks are skipped (example code may
+  carry real values).
+- **`generate.mjs` — `renderTokenView(tree)` + `checkView` + CLI**: renders the
+  value-bearing reference *from* the tokens as a `GENERATED — DO NOT EDIT`
+  artifact (aliases resolved to their terminal, the reference shown), and a
+  `--check` mode regenerates in memory and fails on any divergence — kuat's
+  `tokens:check`, generalised. This is what makes value tables drift-proof by
+  construction; the drift linter is the backstop for everything *not* generated.
+- **`gate.mjs` — `runGate({ tokens, docs })`** + CLI: runs DTCG + value-drift.
+  Generated docs (the token views themselves) are skipped — their drift is the
+  regenerate-diff check's job, not this one.
+
+```
+node tooling/design/generate.mjs <tokens.json> <out.md> [--check]
+node tooling/design/gate.mjs <tokens.json> <doc-or-dir>...
+```
+
+Both exit non-zero on any finding.
+
+## Run the tooling's own tests
+
+```
+cd tooling && npm test     # node --test, zero deps
+```
+
+## Known limits (by design)
+
+The drift check trades a little recall for near-zero false positives — a gate that
+fires on correct prose gets switched off. So non-prose spans are skipped (code,
+fenced and inline; markdown link destinations; URLs; asset/file paths — all places
+a value is *referenced*, not re-typed), and it deliberately does **not** catch: a
+re-typed value whose whitespace/leading-zero differs from the token
+(`rgb(23, 149, 212)` vs `rgb(23,149,212)`, `.5rem` vs `0.5rem`); bare unitless
+numbers and percentages (owned by the generated views). The **generator +
+regenerate-diff** check (`generate.mjs`) is what makes the value-bearing views
+drift-proof by construction; this drift linter is the prose backstop.
+
+## Wired into the capabilities
+
+The design capabilities emit this tooling **and** the `templates/design/` CI
+workflow into the pack they produce, with the regenerate-diff + gate as the
+capability's postcondition — a conversion isn't "done" until they pass. See
+`templates/design/README.md` for the path convention and the exact commands.

package/design/dtcg.mjs

@@ -0,0 +1,135 @@
+// Deterministic DTCG token-file validation, Node built-ins only — so a produced
+// pack runs it with no install. The checks here are the ones a faithful design
+// converter must not be trusted to satisfy by prose alone: a node is a token
+// XOR a group, a dimension value is a real value not a CSS expression, every
+// {alias} resolves, and the $schema is the real published one.
+
+const REF_RE = /^\{([^}]+)\}$/;
+
+/** The one real, published DTCG format schema. A fabricated URL (e.g.
+ * design-tokens.org/schema.json) 404s a validator, so it is a finding. */
+export const DTCG_SCHEMA = 'https://tr.designtokens.org/format/';
+
+const isObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+
+/** Whether a string is a single DTCG alias reference like `{color.blue.500}`. */
+export const isRef = (v) => typeof v === 'string' && REF_RE.test(v.trim());
+
+/** The dotted path inside an alias reference, or null if it isn't one. */
+export const refPath = (v) => (isRef(v) ? v.trim().match(REF_RE)[1] : null);
+
+/** Child members of a node: keys not prefixed with `$` whose value is an object
+ * (a nested token or group). `$type`/`$value`/`$description`/`$extensions` are
+ * the token's own metadata, never children. */
+const children = (node) =>
+  Object.entries(node).filter(([k, v]) => !k.startsWith('$') && isObject(v));
+
+const looksLikeExpression = (s) => typeof s === 'string' && /[a-z]+\s*\(/i.test(s);
+
+/** A concrete dimension value: a string carrying a number ("16px", ".5rem") or
+ * the DTCG object form `{ value, unit }`. */
+const validDimension = (v) =>
+  (typeof v === 'string' && /\d/.test(v)) ||
+  (isObject(v) && typeof v.value === 'number' && typeof v.unit === 'string');
+
+/** Resolve an alias to its terminal token, following chains and refusing cycles.
+ * Returns { ok, token, path } or { ok:false, reason }. */
+function resolve(root, path, seen = new Set()) {
+  if (seen.has(path)) return { ok: false, reason: 'cycle' };
+  seen.add(path);
+  let node = root;
+  for (const seg of path.split('.')) {
+    if (!isObject(node) || !(seg in node)) return { ok: false, reason: 'missing' };
+    node = node[seg];
+  }
+  if (!isObject(node) || !('$value' in node)) return { ok: false, reason: 'not-a-token' };
+  if (isRef(node.$value)) return resolve(root, refPath(node.$value), seen);
+  return { ok: true, token: node, path };
+}
+
+/** Resolve a token `$value` to its terminal literal, following aliases. Returns
+ * the literal (string / number / DTCG object) or `null` when it doesn't
+ * resolve. A non-alias value is returned as-is. */
+export function resolvedLiteral(root, value) {
+  if (!isRef(value)) return value;
+  const r = resolve(root, refPath(value));
+  return r.ok ? r.token.$value : null;
+}
+
+/** Validate a parsed DTCG token tree. Returns a flat list of findings
+ * `{ path, code, message }` — empty when the tree is well-formed. Pure and
+ * deterministic: the same tree always yields the same findings, in tree order. */
+export function validateDtcg(root, { schema = DTCG_SCHEMA } = {}) {
+  const findings = [];
+  const at = (p) => p || '(root)';
+
+  if (isObject(root) && '$schema' in root && root.$schema !== schema) {
+    findings.push({
+      path: '$schema',
+      code: 'BAD_SCHEMA',
+      message: `$schema is "${root.$schema}", not the real DTCG schema (${schema}).`,
+    });
+  }
+
+  const walk = (node, path, inheritedType) => {
+    if (!isObject(node)) return;
+    // A group's $type is inherited by its descendant tokens (DTCG).
+    const type = '$type' in node ? node.$type : inheritedType;
+    const isToken = '$value' in node;
+    const kids = children(node);
+
+    if (isToken && kids.length > 0) {
+      findings.push({
+        path: at(path),
+        code: 'TOKEN_AND_GROUP',
+        message: `node is both a token ($value) and a group (has child tokens: ${kids
+          .map(([k]) => k)
+          .join(', ')}) — DTCG nodes are one or the other.`,
+      });
+    }
+
+    if (isToken) {
+      const value = node.$value;
+      if (isRef(value)) {
+        // An alias's type is the referent's, so it needs no $type of its own.
+        const r = resolve(root, refPath(value));
+        if (!r.ok) {
+          findings.push({
+            path: at(path),
+            code: r.reason === 'cycle' ? 'REF_CYCLE' : 'UNRESOLVED_REF',
+            message: `$value alias ${value} ${r.reason === 'cycle' ? 'is part of a reference cycle' : 'does not resolve to a token'}.`,
+          });
+        }
+      } else if (type === undefined) {
+        findings.push({
+          path: at(path),
+          code: 'TOKEN_MISSING_TYPE',
+          message: `token has a $value but no $type (own or inherited from a group) — DTCG requires a resolvable type.`,
+        });
+      } else if (type === 'dimension' && looksLikeExpression(value)) {
+        findings.push({
+          path: at(path),
+          code: 'EXPRESSION_DIMENSION',
+          message: `dimension $value "${value}" is a CSS expression, which no DTCG parser accepts — use a concrete value.`,
+        });
+      } else if (type === 'dimension' && !validDimension(value)) {
+        findings.push({
+          path: at(path),
+          code: 'BAD_DIMENSION_VALUE',
+          message: `dimension $value is not a concrete dimension (expected "16px" or { value, unit }).`,
+        });
+      }
+    } else if (kids.length === 0 && '$type' in node) {
+      findings.push({
+        path: at(path),
+        code: 'TOKEN_MISSING_VALUE',
+        message: `node has $type but no $value and no children — a token must carry a $value.`,
+      });
+    }
+
+    for (const [k, v] of kids) walk(v, path ? `${path}.${k}` : k, type);
+  };
+
+  walk(root, '', undefined);
+  return findings;
+}

package/design/gate.mjs

@@ -0,0 +1,87 @@
+// The deterministic design gate the capabilities emit into a produced pack and
+// wire into CI: validate the token source as DTCG, and assert no value-free doc
+// re-types a token value. Zero dependencies, so the pack runs it with no install.
+//
+// Usage (from the pack root):
+//   node tooling/design/gate.mjs <tokens.json> <doc-or-dir>...
+// Exits non-zero on any finding; prints each with its location.
+
+import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateDtcg } from './dtcg.mjs';
+import { tokenLiterals, findValueDrift } from './value-drift.mjs';
+
+const GENERATED_MARK = 'GENERATED FILE — DO NOT EDIT';
+
+/** Run both deterministic checks over an already-read token source and a set of
+ * already-read docs. Pure: the same inputs always yield the same result, so the
+ * gate is reproducible. A generated doc is the token view itself and is skipped
+ * — its drift is owned by the regenerate-diff check, not this one. */
+export function runGate({ tokens, docs = [] }) {
+  const dtcg = validateDtcg(tokens);
+  const literals = tokenLiterals(tokens);
+  const drift = docs
+    .filter(({ text }) => !text.includes(GENERATED_MARK))
+    .flatMap(({ path, text }) => findValueDrift(literals, text).map((f) => ({ ...f, path })));
+  return { ok: dtcg.length === 0 && drift.length === 0, dtcg, drift };
+}
+
+/** Collect `.md` files under a path. Symlinks are NOT followed (so a symlink
+ * loop can't hang the gate); node_modules/.git are skipped; an unreadable entry
+ * is skipped rather than thrown. */
+export function markdownFilesUnder(target) {
+  const out = [];
+  const visit = (p) => {
+    let s;
+    try {
+      s = lstatSync(p);
+    } catch {
+      return;
+    }
+    if (s.isSymbolicLink()) return;
+    if (s.isDirectory()) {
+      if (/(^|\/)(node_modules|\.git)(\/|$)/.test(p)) return;
+      for (const name of readdirSync(p)) visit(join(p, name));
+    } else if (s.isFile() && p.endsWith('.md')) {
+      out.push(p);
+    }
+  };
+  visit(target);
+  return out;
+}
+
+export function main(argv) {
+  const [tokensPath, ...docTargets] = argv;
+  if (!tokensPath) {
+    console.error('usage: node gate.mjs <tokens.json> <doc-or-dir>...');
+    return 2;
+  }
+  let tokens;
+  try {
+    tokens = JSON.parse(readFileSync(tokensPath, 'utf8'));
+  } catch (e) {
+    console.error(`cannot read tokens file ${tokensPath}: ${e.message}`);
+    return 2;
+  }
+  // A named doc target that doesn't exist is a misconfiguration, not "no docs" —
+  // silently scanning nothing would turn the gate green on a CI path typo.
+  for (const t of docTargets) {
+    try {
+      lstatSync(t);
+    } catch {
+      console.error(`doc target not found: ${t}`);
+      return 2;
+    }
+  }
+  const docPaths = docTargets.flatMap(markdownFilesUnder);
+  const docs = docPaths.map((path) => ({ path, text: readFileSync(path, 'utf8') }));
+  const { ok, dtcg, drift } = runGate({ tokens, docs });
+
+  for (const f of dtcg) console.error(`DTCG ${f.code} at ${f.path}: ${f.message}`);
+  for (const f of drift)
+    console.error(`DRIFT ${f.path}:${f.line} re-types token value ${f.value} — point at the token instead`);
+  console.error(ok ? 'design gate ok' : `design gate FAILED: ${dtcg.length} DTCG + ${drift.length} drift finding(s)`);
+  return ok ? 0 : 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main(process.argv.slice(2)));

package/design/generate.mjs

@@ -0,0 +1,140 @@
+// The token → value-view generator, and its regenerate-diff drift check (kuat's
+// `tokens:check`, generalised to any DTCG token file). The value-bearing
+// reference is a GENERATED artifact: a model authors the tokens (the source of
+// truth) and value-free prose, and this renders the value tables deterministically
+// — so they can never silently drift. The check regenerates in memory and asserts
+// the committed file matches exactly. Zero dependencies (Node built-ins).
+//
+// Usage (from the pack root):
+//   node tooling/design/generate.mjs <tokens.json> <out.md>            # write
+//   node tooling/design/generate.mjs <tokens.json> <out.md> --check    # verify
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolvedLiteral, isRef } from './dtcg.mjs';
+
+/** The marker the drift gate (value-drift.mjs) recognises to skip a generated
+ * doc — its faithfulness is this check's job, not the prose linter's. */
+export const GENERATED_MARK = 'GENERATED FILE — DO NOT EDIT';
+
+const isObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+// Escape what would corrupt a table cell: a literal pipe, and a newline (which
+// would split the row). Keeps the rendered markdown well-formed and stable.
+const cell = (s) => String(s).replace(/\|/g, '\\|').replace(/\r?\n/g, '\\n');
+
+function formatValue(v) {
+  if (v === null || v === undefined) return '(unresolved)';
+  // A canonical DTCG dimension is exactly { value, unit }. Anything carrying
+  // extra keys is not collapsed to `<value><unit>` — that would hide a drift in
+  // the extra field — so it falls through to the full JSON form.
+  if (isObject(v) && 'value' in v && 'unit' in v && Object.keys(v).length === 2)
+    return `${v.value}${v.unit}`;
+  if (typeof v === 'string' || typeof v === 'number') return String(v);
+  return JSON.stringify(v);
+}
+
+/** Flatten the tree to its tokens in document order, carrying the inherited
+ * `$type` so a token under a typed group still reports its type. */
+function collectTokens(root) {
+  const out = [];
+  const walk = (node, path, inheritedType) => {
+    if (!isObject(node)) return;
+    const type = '$type' in node ? node.$type : inheritedType;
+    if ('$value' in node) out.push({ path, type, value: node.$value });
+    for (const [k, v] of Object.entries(node))
+      if (!k.startsWith('$') && isObject(v)) walk(v, path ? `${path}.${k}` : k, type);
+  };
+  walk(root, '', undefined);
+  return out;
+}
+
+/** Render the deterministic value view for a token tree: a banner, then one
+ * table per top-level group listing each token's resolved value (aliases
+ * resolved to their terminal, with the reference shown). Pure and stable — the
+ * same tree always renders byte-identically, so it can self-diff. */
+export function renderTokenView(root) {
+  const groups = new Map();
+  for (const t of collectTokens(root)) {
+    const g = t.path.split('.')[0];
+    if (!groups.has(g)) groups.set(g, []);
+    groups.get(g).push(t);
+  }
+
+  // The banner carries no path — the output must not depend on how it was
+  // invoked, or the author's spelling and CI's `./`-prefixed `find` spelling
+  // would disagree and a faithful view would fail --check.
+  const lines = [
+    `<!-- ${GENERATED_MARK} BY HAND.`,
+    '     Produced from the design tokens by tooling/design/generate.mjs.',
+    '     Change a value at the token source and regenerate; a drift check gates this file. -->',
+    '',
+    '# Design tokens',
+  ];
+  for (const [group, rows] of groups) {
+    lines.push('', `## ${group}`, '', '| Token | Type | Value | Alias |', '| --- | --- | --- | --- |');
+    for (const { path, type, value } of rows) {
+      const resolved = formatValue(resolvedLiteral(root, value));
+      const alias = isRef(value) ? value : '';
+      lines.push(`| ${cell(path)} | ${cell(type ?? '')} | ${cell(resolved)} | ${cell(alias)} |`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+/** Compare a freshly-rendered view against the committed one. `{ ok }` when
+ * identical, else the first differing line and both sides. */
+export function checkView(rendered, committed) {
+  if (rendered === committed) return { ok: true };
+  const a = rendered.split('\n');
+  const b = committed.split('\n');
+  const n = Math.max(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    if (a[i] !== b[i]) return { ok: false, line: i + 1, expected: a[i] ?? '(eof)', actual: b[i] ?? '(eof)' };
+  }
+  return { ok: false, line: n, expected: '', actual: '' };
+}
+
+export function main(argv) {
+  const check = argv.includes('--check');
+  const [tokensPath, outPath] = argv.filter((a) => a !== '--check');
+  if (!tokensPath || !outPath) {
+    console.error('usage: node generate.mjs <tokens.json> <out.md> [--check]');
+    return 2;
+  }
+  let tokens;
+  try {
+    tokens = JSON.parse(readFileSync(tokensPath, 'utf8'));
+  } catch (e) {
+    console.error(`cannot read tokens file ${tokensPath}: ${e.message}`);
+    return 2;
+  }
+  const rendered = renderTokenView(tokens);
+
+  if (check) {
+    let committed = '';
+    try {
+      committed = readFileSync(outPath, 'utf8');
+    } catch {
+      committed = '';
+    }
+    const r = checkView(rendered, committed);
+    if (r.ok) {
+      console.error(`tokens:check ok — ${outPath} matches ${tokensPath}`);
+      return 0;
+    }
+    console.error(`tokens:check FAILED — ${outPath} has drifted from ${tokensPath} at line ${r.line}:`);
+    console.error(`  expected: ${r.expected}`);
+    console.error(`  actual:   ${r.actual}`);
+    return 1;
+  }
+
+  try {
+    writeFileSync(outPath, rendered);
+  } catch (e) {
+    console.error(`cannot write ${outPath}: ${e.message}`);
+    return 2;
+  }
+  console.error(`wrote ${outPath} from ${tokensPath}`);
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main(process.argv.slice(2)));

package/design/index.mjs

@@ -0,0 +1,10 @@
+// @verevoir/design-gate — the deterministic design verifier, zero-dependency.
+// The same code the design capabilities emit into a produced pack (for that
+// pack's CI) AND the consuming runtime imports to enforce a capability's
+// `verify: design-pack` as a hard postcondition. One source, two consumers.
+
+export { verifyFiles, verifyPack } from './verify-pack.mjs';
+export { renderTokenView, checkView, GENERATED_MARK } from './generate.mjs';
+export { validateDtcg, DTCG_SCHEMA, isRef, refPath, resolvedLiteral } from './dtcg.mjs';
+export { tokenLiterals, findValueDrift } from './value-drift.mjs';
+export { runGate } from './gate.mjs';

package/design/value-drift.mjs

@@ -0,0 +1,82 @@
+// The value-drift backstop: a token value must live once, in the tokens — a
+// concept doc points at it, never re-types it. This asserts no value-free doc
+// contains a literal token value. It is deliberately high-signal, not
+// exhaustive: it matches only DISTINCTIVE literals (a hex colour, a dimension
+// carrying a unit, a colour function, a percentage) where an occurrence in prose
+// is unambiguously a re-typed value; bare unitless numbers (font weights, a
+// type-scale step) are owned by the generated value views, not grepped here,
+// because "700" in prose is all noise. Fenced code blocks are skipped — example
+// code is meant to carry real values.
+
+const isObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const isRef = (v) => typeof v === 'string' && /^\{[^}]+\}$/.test(v.trim());
+
+const HEX = /#[0-9a-fA-F]{3,8}/g;
+const DIMENSION = /-?\d*\.?\d+(?:px|rem|em)/g;
+const COLOR_FN = /(?:oklch|rgba?|hsla?)\([^)]*\)/gi;
+
+/** Pull the distinctive value literals out of one token `$value` (a string, or a
+ * DTCG dimension object `{value,unit}`), lower-cased so matching is stable. */
+function literalsOf(value) {
+  const out = [];
+  if (isObject(value) && 'value' in value && 'unit' in value) {
+    out.push(`${value.value}${value.unit}`.toLowerCase());
+    return out;
+  }
+  if (typeof value !== 'string' || isRef(value)) return out;
+  for (const re of [HEX, COLOR_FN, DIMENSION]) {
+    const m = value.match(re);
+    if (m) out.push(...m.map((s) => s.toLowerCase()));
+  }
+  return out;
+}
+
+/** The set of distinctive value literals a doc must not re-type. Walks the token
+ * tree collecting every concrete `$value` (aliases are pointers, so skipped). */
+export function tokenLiterals(root) {
+  const set = new Set();
+  const walk = (node) => {
+    if (!isObject(node)) return;
+    if ('$value' in node) for (const lit of literalsOf(node.$value)) set.add(lit);
+    for (const [k, v] of Object.entries(node)) if (!k.startsWith('$') && isObject(v)) walk(v);
+  };
+  walk(root);
+  return set;
+}
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Find re-typed token values in a doc's prose. `literals` is the set from
+ * `tokenLiterals`. Returns `{ value, line, snippet }[]` in document order;
+ * empty when the doc only points at values. Fenced code blocks are ignored. */
+export function findValueDrift(literals, docText) {
+  if (literals.size === 0) return [];
+  // A literal preceded/followed by a hex digit or letter is part of a longer
+  // token (e.g. "16px" inside "216px"), so require a non-alphanumeric edge.
+  const alternation = [...literals].map(escape).join('|');
+  const re = new RegExp(`(?<![0-9a-z])(${alternation})(?![0-9a-z])`, 'gi');
+
+  const findings = [];
+  let inFence = false;
+  const lines = docText.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    // Blank the non-prose spans before matching — a value in code, a link
+    // destination, a URL, or an asset/file path is referenced, not re-typed.
+    const blank = (m) => ' '.repeat(m.length);
+    const scan = line
+      .replace(/`[^`]*`/g, blank) // inline code
+      .replace(/\]\([^)]*\)/g, blank) // markdown link destination
+      .replace(/<?\bhttps?:\/\/[^\s>)]+>?/gi, blank) // bare / autolink URL
+      .replace(/[\w./-]+\.(?:svg|png|jpe?g|gif|webp|css|scss|sass|less|js|ts|json|md|html?)\b/gi, blank); // asset / file path
+    for (const m of scan.matchAll(re)) {
+      findings.push({ value: m[1].toLowerCase(), line: i + 1, snippet: line.trim() });
+    }
+  }
+  return findings;
+}

package/design/verify-pack.mjs

@@ -0,0 +1,136 @@
+// verify-pack — the deterministic "verify" a design capability's execution runs.
+// For every token file in a produced pack it validates DTCG, regenerate-diffs the
+// generated view, and value-drift-scans the reference docs, returning aggregated,
+// model-actionable findings so an execution loop can re-prompt until green.
+//
+// Two entry points:
+//   verifyFiles(files) — PURE, over an in-memory { path → content } map; the
+//     runtime calls this on files read back from the branch the model wrote to.
+//   verifyPack(root)   — the CLI/local wrapper: read the pack off disk into a
+//     file map and delegate to verifyFiles.
+// Zero dependencies (Node built-ins).
+//   node tooling/design/verify-pack.mjs <pack-root>   0 = clean, 1 = findings, 2 = no tokens
+
+import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateDtcg } from './dtcg.mjs';
+import { renderTokenView, checkView } from './generate.mjs';
+import { runGate } from './gate.mjs';
+
+const TOKEN_FILE = /(^|\/)design-language\/tokens\/[^/]+\.tokens\.json$/;
+
+/** Drop duplicate findings — two token files sharing a literal would otherwise
+ * flag the same re-typed value twice; findings feed back to the model, so keep
+ * them noise-free. */
+function result(findings) {
+  const seen = new Set();
+  const deduped = findings.filter((f) => {
+    const key = JSON.stringify([f.kind, f.file, f.where, f.message]);
+    return seen.has(key) ? false : (seen.add(key), true);
+  });
+  return { ok: deduped.length === 0, findings: deduped };
+}
+
+/** Verify a produced design pack held as an in-memory `{ path → content }` map
+ * (paths use `/`). A path under `design-language/tokens/` ending `.tokens.json`
+ * is a token source; its sibling `.tokens.md` is the generated view; the `.md`
+ * files under the same `design-language/` dir are the concept docs. Pure: same
+ * files → same findings (`{ kind, file, where?, message }`; kinds NO_TOKENS /
+ * PARSE / DTCG / VIEW_DRIFT / VALUE_DRIFT). */
+export function verifyFiles(files) {
+  // Total against malformed input — this is the gate the runtime calls on files
+  // it reads back, so a missing/odd value degrades to a finding, never a throw.
+  const map =
+    files instanceof Map
+      ? files
+      : new Map(files && typeof files === 'object' ? Object.entries(files) : []);
+  const tokenPaths = [...map.keys()].filter((p) => TOKEN_FILE.test(p)).sort();
+  if (tokenPaths.length === 0) {
+    return {
+      ok: false,
+      findings: [
+        { kind: 'NO_TOKENS', message: 'no design-language/tokens/*.tokens.json in the pack' },
+      ],
+    };
+  }
+
+  const findings = [];
+  for (const tp of tokenPaths) {
+    let tokens;
+    try {
+      tokens = JSON.parse(String(map.get(tp) ?? ''));
+    } catch (e) {
+      findings.push({ kind: 'PARSE', file: tp, message: e.message });
+      continue;
+    }
+
+    for (const f of validateDtcg(tokens))
+      findings.push({ kind: 'DTCG', file: tp, where: f.path, message: `${f.code}: ${f.message}` });
+
+    const viewPath = tp.replace(/\.json$/, '.md');
+    if (!checkView(renderTokenView(tokens), String(map.get(viewPath) ?? '')).ok)
+      findings.push({
+        kind: 'VIEW_DRIFT',
+        file: viewPath,
+        message: `generated view is missing or stale — run: node tooling/design/generate.mjs ${tp} ${viewPath}`,
+      });
+
+    // Concept docs: the `.md` files under this token file's `design-language/` dir.
+    const dlPrefix = tp.replace(/tokens\/[^/]+\.tokens\.json$/, '');
+    const docs = [...map.entries()]
+      .filter(([p]) => p.endsWith('.md') && p.startsWith(dlPrefix))
+      .map(([path, text]) => ({ path, text: String(text ?? '') }));
+    for (const d of runGate({ tokens, docs }).drift)
+      findings.push({
+        kind: 'VALUE_DRIFT',
+        file: d.path,
+        where: `line ${d.line}`,
+        message: `re-types token value ${d.value} — point at the token instead`,
+      });
+  }
+  return result(findings);
+}
+
+/** Read a pack off disk into a `{ path → content }` map (paths relative to
+ * `root`, only `*.tokens.json` + `*.md`) and verify it. Symlinks not followed;
+ * node_modules/.git skipped. */
+export function verifyPack(root) {
+  const files = new Map();
+  const visit = (abs, rel) => {
+    let s;
+    try {
+      s = lstatSync(abs);
+    } catch {
+      return;
+    }
+    if (s.isSymbolicLink()) return;
+    if (s.isDirectory()) {
+      if (/(^|\/)(node_modules|\.git)(\/|$)/.test(abs)) return;
+      for (const n of readdirSync(abs)) visit(join(abs, n), rel ? `${rel}/${n}` : n);
+    } else if (s.isFile() && (abs.endsWith('.tokens.json') || abs.endsWith('.md'))) {
+      try {
+        files.set(rel, readFileSync(abs, 'utf8'));
+      } catch {
+        // skip an unreadable file
+      }
+    }
+  };
+  visit(root, '');
+  return verifyFiles(files);
+}
+
+function main(argv) {
+  const root = argv[0];
+  if (!root) {
+    console.error('usage: node verify-pack.mjs <pack-root>');
+    return 2;
+  }
+  const { ok, findings } = verifyPack(root);
+  for (const f of findings)
+    console.error(`${f.kind} ${f.file ?? ''}${f.where ? ` ${f.where}` : ''}: ${f.message}`);
+  console.error(ok ? 'verify-pack ok' : `verify-pack FAILED: ${findings.length} finding(s)`);
+  if (findings.some((f) => f.kind === 'NO_TOKENS')) return 2;
+  return ok ? 0 : 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main(process.argv.slice(2)));

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@verevoir/design-gate",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Zero-dependency deterministic design verifier: DTCG token validation, regenerate-diff of generated views, and value-drift checks over a design pack. The same code the design capabilities emit into a produced pack (its CI) and the runtime imports to enforce a capability's `verify: design-pack` postcondition.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verevoir/aigency-guardrails.git",
+    "directory": "tooling"
+  },
+  "exports": {
+    ".": "./design/index.mjs"
+  },
+  "files": [
+    "design/index.mjs",
+    "design/dtcg.mjs",
+    "design/gate.mjs",
+    "design/generate.mjs",
+    "design/value-drift.mjs",
+    "design/verify-pack.mjs",
+    "design/README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}