@urbicon-ui/mcp-server 6.1.4

package/src/design-manifest/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Public API of the design-manifest module — the persistent design-intent layer
+ * (docs/DESIGN-MCP.md, Option C). Consumed by the `get_design_context`,
+ * `record_design_decision`, and `sync_design_manifest` MCP tools.
+ */
+
+export {
+  appendDecision,
+  createManifestTemplate,
+  DECISIONS_HEADING,
+  emptyManifest,
+  formatContext,
+  parseFrontmatter,
+  parseManifest,
+  renderDecision,
+  USAGES_HEADING,
+  upsertUsagesSection
+} from './manifest.js';
+export { scanMarkers } from './scan.js';
+export type { DesignDecision, DesignManifest, PatternUsage } from './types.js';

package/src/design-manifest/manifest.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import {
+  appendDecision,
+  createManifestTemplate,
+  formatContext,
+  parseFrontmatter,
+  parseManifest,
+  upsertUsagesSection
+} from './manifest.js';
+import type { DesignDecision } from './types.js';
+
+describe('parseFrontmatter', () => {
+  it('reads flat key:value pairs and strips the block from the body', () => {
+    const { data, body } = parseFrontmatter(
+      '---\nparadigm: corporate\ntheme: "ocean"\n---\n# Title\nrest'
+    );
+    expect(data).toEqual({ paradigm: 'corporate', theme: 'ocean' });
+    expect(body).toBe('# Title\nrest');
+  });
+  it('returns empty data when there is no frontmatter', () => {
+    const { data, body } = parseFrontmatter('# No frontmatter');
+    expect(data).toEqual({});
+    expect(body).toBe('# No frontmatter');
+  });
+});
+
+describe('manifest template + parse round-trip', () => {
+  const template = createManifestTemplate({
+    paradigm: 'corporate',
+    theme: 'ocean',
+    projectName: 'Acme'
+  });
+
+  it('parses its own scaffold', () => {
+    const m = parseManifest(template);
+    expect(m.frontmatter.paradigm).toBe('corporate');
+    expect(m.frontmatter.theme).toBe('ocean');
+    expect(m.usages).toEqual([]);
+    expect(m.decisions).toEqual([]);
+    expect(m.exists).toBe(true);
+  });
+});
+
+describe('upsertUsagesSection', () => {
+  const template = createManifestTemplate({});
+  const usages = [
+    { pattern: 'dashboard', file: 'src/routes/dashboard/+page.svelte' },
+    { pattern: 'form-page', file: 'src/routes/signup/+page.svelte' }
+  ];
+
+  it('fills the generated block and is re-parseable', () => {
+    const updated = upsertUsagesSection(template, usages);
+    const m = parseManifest(updated);
+    expect(m.usages).toHaveLength(2);
+    expect(m.usages).toContainEqual({
+      pattern: 'dashboard',
+      file: 'src/routes/dashboard/+page.svelte'
+    });
+  });
+
+  it('is idempotent — replacing the block, not appending', () => {
+    const once = upsertUsagesSection(template, usages);
+    const twice = upsertUsagesSection(once, usages);
+    expect(twice).toBe(once);
+  });
+
+  it('removes stale usages on the next sync', () => {
+    const withTwo = upsertUsagesSection(template, usages);
+    const withOne = upsertUsagesSection(withTwo, [usages[0]!]);
+    expect(parseManifest(withOne).usages).toHaveLength(1);
+  });
+
+  it('appends a Pattern Usages section when none exists', () => {
+    const bare = '# Bare manifest\n\nsome prose\n';
+    const updated = upsertUsagesSection(bare, usages);
+    expect(updated).toContain('## Pattern Usages');
+    expect(parseManifest(updated).usages).toHaveLength(2);
+    expect(updated).toContain('some prose'); // original content preserved
+  });
+});
+
+describe('appendDecision', () => {
+  const dec = (title: string, date: string): DesignDecision => ({
+    date,
+    title,
+    status: 'accepted',
+    decision: `do ${title}`,
+    rationale: `because ${title}`
+  });
+
+  it('adds a decision into the existing section, newest first', () => {
+    const t = createManifestTemplate({});
+    const one = appendDecision(t, dec('first', '2026-06-01'));
+    const two = appendDecision(one, dec('second', '2026-06-02'));
+    const m = parseManifest(two);
+    expect(m.decisions.map((d) => d.title)).toEqual(['second', 'first']);
+    expect(m.decisions[0]!.rationale).toBe('because second');
+  });
+
+  it('creates the section when absent and preserves frontmatter + usages', () => {
+    const withUsage = upsertUsagesSection(createManifestTemplate({ paradigm: 'brutalist' }), [
+      { pattern: 'dashboard', file: 'a.svelte' }
+    ]);
+    const updated = appendDecision(withUsage, dec('x', '2026-06-13'));
+    const m = parseManifest(updated);
+    expect(m.frontmatter.paradigm).toBe('brutalist');
+    expect(m.usages).toHaveLength(1);
+    expect(m.decisions).toHaveLength(1);
+  });
+});
+
+describe('formatContext', () => {
+  it('summarises intake, usages and decisions', () => {
+    let content = createManifestTemplate({ paradigm: 'corporate', theme: 'ocean' });
+    content = upsertUsagesSection(content, [{ pattern: 'dashboard', file: 'a.svelte' }]);
+    content = appendDecision(content, {
+      date: '2026-06-13',
+      title: 'Tabs for settings',
+      status: 'accepted',
+      decision: 'use tabs'
+    });
+    const out = formatContext(parseManifest(content));
+    expect(out).toContain('corporate');
+    expect(out).toContain('`dashboard`');
+    expect(out).toContain('Tabs for settings');
+  });
+
+  it('guides the user when the manifest is empty', () => {
+    const out = formatContext(parseManifest(createManifestTemplate({})));
+    expect(out).toContain('data-design-pattern');
+    expect(out).toContain('record_design_decision');
+  });
+});
+
+describe('review hardening', () => {
+  it('does not interpret `$` sequences in a file path as replacement patterns', () => {
+    // Heading present, no marker block yet → the String.replace fallback branch.
+    const bare = '# M\n\n## Pattern Usages\n';
+    const updated = upsertUsagesSection(bare, [
+      { pattern: 'dashboard', file: "src/o'$&-$1/+page.svelte" }
+    ]);
+    expect(updated).toContain("src/o'$&-$1/+page.svelte");
+    expect(parseManifest(updated).usages[0]?.file).toBe("src/o'$&-$1/+page.svelte");
+  });
+
+  it('replaces an orphaned start marker (lost end marker) without duplicating usages', () => {
+    const orphaned =
+      '## Pattern Usages\n\n<!-- AUTO-GENERATED pattern usages — managed by sync_design_manifest; do not edit by hand -->\n\n- `dashboard` — old.svelte\n\n## Design Decisions\n';
+    const updated = upsertUsagesSection(orphaned, [{ pattern: 'form-page', file: 'new.svelte' }]);
+    const usages = parseManifest(updated).usages;
+    expect(usages).toHaveLength(1);
+    expect(usages[0]).toEqual({ pattern: 'form-page', file: 'new.svelte' });
+    expect(updated).toContain('## Design Decisions'); // following section preserved
+  });
+
+  it('collapses multi-line decision/rationale text to a single line (no truncation on re-parse)', () => {
+    const updated = appendDecision(createManifestTemplate({}), {
+      date: '2026-06-13',
+      title: 'Cache strategy',
+      status: 'accepted',
+      decision: 'Use SWR.\nFallback to stale for 30s.',
+      rationale: 'Line one.\r\nLine two.'
+    });
+    const d = parseManifest(updated).decisions[0]!;
+    expect(d.decision).toBe('Use SWR. Fallback to stale for 30s.');
+    expect(d.rationale).toBe('Line one. Line two.');
+  });
+
+  it('tolerates CRLF frontmatter', () => {
+    const { data } = parseFrontmatter(
+      '---\r\nparadigm: brutalist\r\ntheme: forest\r\n---\r\n# Title'
+    );
+    expect(data).toEqual({ paradigm: 'brutalist', theme: 'forest' });
+  });
+});

package/src/design-manifest/manifest.ts

@@ -0,0 +1,250 @@
+/**
+ * Parse and edit a `design.manifest.md`. Deliberately dependency-free (no YAML
+ * lib — consistent with the zero-dep ethos): frontmatter is flat `key: value`,
+ * and edits are surgical (replace one marked block / insert one ADR) so any
+ * hand-written prose, ordering, and formatting survive a round-trip.
+ */
+
+import type { DesignDecision, DesignManifest, PatternUsage } from './types.js';
+
+const USAGES_HEADING = '## Pattern Usages';
+const DECISIONS_HEADING = '## Design Decisions';
+const USAGES_START =
+  '<!-- AUTO-GENERATED pattern usages — managed by sync_design_manifest; do not edit by hand -->';
+const USAGES_END = '<!-- END pattern usages -->';
+
+/** Split leading `--- … ---` frontmatter from the body. Returns flat key→value pairs. */
+export function parseFrontmatter(content: string): { data: Record<string, string>; body: string } {
+  const data: Record<string, string> = {};
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { data, body: content };
+
+  for (const line of match[1]!.split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z][\w-]*)\s*:\s*(.*)$/);
+    if (kv) {
+      const value = kv[2]!.trim().replace(/^["']|["']$/g, '');
+      if (value) data[kv[1]!] = value;
+    }
+  }
+  return { data, body: content.slice(match[0].length) };
+}
+
+/** Extract the `## …` section body for a given heading (until the next `## ` or EOF). */
+function extractSection(body: string, heading: string): string | null {
+  const lines = body.split('\n');
+  const start = lines.findIndex((l) => l.trim() === heading);
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i]!)) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+function parseUsages(body: string): PatternUsage[] {
+  const section = extractSection(body, USAGES_HEADING);
+  if (!section) return [];
+  const usages: PatternUsage[] = [];
+  for (const m of section.matchAll(/^- `([a-z0-9-]+)`\s+—\s+(.+)$/gm)) {
+    usages.push({ pattern: m[1]!, file: m[2]!.trim() });
+  }
+  return usages;
+}
+
+function parseDecisions(body: string): DesignDecision[] {
+  const section = extractSection(body, DECISIONS_HEADING);
+  if (!section) return [];
+  const decisions: DesignDecision[] = [];
+  // Each decision is a `### <date> — <title>` block.
+  const blocks = section.split(/^### /m).slice(1);
+  for (const block of blocks) {
+    const headerLine = block.split('\n', 1)[0]!;
+    const header = headerLine.match(/^(\d{4}-\d{2}-\d{2})\s+—\s+(.+)$/);
+    if (!header) continue;
+    const field = (name: string): string | undefined =>
+      block.match(new RegExp(`\\*\\*${name}:\\*\\*\\s*(.+)`))?.[1]?.trim();
+    decisions.push({
+      date: header[1]!,
+      title: header[2]!.trim(),
+      status: field('Status') ?? 'accepted',
+      decision: field('Decision') ?? '',
+      rationale: field('Rationale')
+    });
+  }
+  return decisions;
+}
+
+/** Parse a manifest file into structured form. */
+export function parseManifest(content: string, exists = true): DesignManifest {
+  const { data, body } = parseFrontmatter(content);
+  return {
+    frontmatter: data,
+    usages: parseUsages(body),
+    decisions: parseDecisions(body),
+    exists
+  };
+}
+
+/** The empty-manifest sentinel returned when no file exists. */
+export function emptyManifest(): DesignManifest {
+  return { frontmatter: {}, usages: [], decisions: [], exists: false };
+}
+
+function renderUsagesBlock(usages: PatternUsage[]): string {
+  const lines = [USAGES_START];
+  if (usages.length === 0) {
+    lines.push('', '_No `data-design-pattern` markers found yet._', '');
+  } else {
+    lines.push('');
+    const sorted = [...usages].sort(
+      (a, b) => a.pattern.localeCompare(b.pattern) || a.file.localeCompare(b.file)
+    );
+    for (const u of sorted) lines.push(`- \`${u.pattern}\` — ${u.file}`);
+    lines.push('');
+  }
+  lines.push(USAGES_END);
+  return lines.join('\n');
+}
+
+/** Replace the auto-generated usages block (or insert the section) — everything else is untouched. */
+export function upsertUsagesSection(content: string, usages: PatternUsage[]): string {
+  const block = renderUsagesBlock(usages);
+  const startIdx = content.indexOf(USAGES_START);
+  if (startIdx !== -1) {
+    const endIdx = content.indexOf(USAGES_END, startIdx);
+    if (endIdx !== -1) {
+      const after = endIdx + USAGES_END.length;
+      return content.slice(0, startIdx) + block + content.slice(after);
+    }
+    // Start marker present but end marker lost (hand-edit / merge): replace from the
+    // start marker to the next section heading so no orphaned block is left to double-count.
+    const nextSection = content.indexOf('\n## ', startIdx);
+    const truncateAt = nextSection !== -1 ? nextSection : content.length;
+    return content.slice(0, startIdx) + block + content.slice(truncateAt);
+  }
+  // No marker block yet — insert after the heading, or append a fresh section.
+  // NB: a function replacer, not a string, so `$`-sequences in a file path can't
+  // be interpreted as replacement patterns (`$'`, `$&`, …).
+  if (content.includes(`\n${USAGES_HEADING}`) || content.startsWith(USAGES_HEADING)) {
+    return content.replace(
+      new RegExp(`(${USAGES_HEADING}\\n)`),
+      (_m, heading: string) => `${heading}\n${block}\n`
+    );
+  }
+  const sep = content.endsWith('\n') ? '\n' : '\n\n';
+  return `${content}${sep}${USAGES_HEADING}\n\n${block}\n`;
+}
+
+/** Collapse newlines to spaces — every ADR field is single-line in the Markdown format. */
+function oneLine(s: string): string {
+  return s.replace(/[\r\n]+/g, ' ').trim();
+}
+
+/** Render one ADR block. */
+export function renderDecision(d: DesignDecision): string {
+  const lines = [
+    `### ${d.date} — ${oneLine(d.title)}`,
+    '',
+    `**Status:** ${oneLine(d.status)}`,
+    '',
+    `**Decision:** ${oneLine(d.decision)}`
+  ];
+  if (d.rationale) lines.push('', `**Rationale:** ${oneLine(d.rationale)}`);
+  return `${lines.join('\n')}\n`;
+}
+
+/** Insert a new ADR at the top of the Design Decisions section (newest first). Creates the section if absent. */
+export function appendDecision(content: string, decision: DesignDecision): string {
+  const block = renderDecision(decision);
+  const m = content.match(/(?:^|\n)## Design Decisions[^\n]*\n/);
+  if (m && m.index !== undefined) {
+    let pos = m.index + m[0].length; // just past the heading line's newline
+    let prefix = '';
+    if (content[pos] === '\n')
+      pos += 1; // keep an existing blank line, insert after it
+    else prefix = '\n'; // no blank line below the heading — add one
+    return `${content.slice(0, pos) + prefix + block}\n${content.slice(pos)}`;
+  }
+  const sep = content.endsWith('\n') ? '\n' : '\n\n';
+  return `${content}${sep}${DECISIONS_HEADING}\n\n${block}`;
+}
+
+/** A starter manifest for a project that has none. */
+export function createManifestTemplate(opts: {
+  paradigm?: string;
+  theme?: string;
+  density?: string;
+  projectName?: string;
+}): string {
+  const fm = [
+    '---',
+    `paradigm: ${opts.paradigm ?? 'minimal'}`,
+    `theme: ${opts.theme ?? 'default'}`,
+    `density: ${opts.density ?? 'comfortable'}`,
+    '---'
+  ].join('\n');
+  return [
+    fm,
+    '',
+    `# Design Manifest${opts.projectName ? ` — ${opts.projectName}` : ''}`,
+    '',
+    'The persistent design intent for this project. Frontmatter records the enforced intake',
+    'decisions (paradigm, theme, density). `## Pattern Usages` is regenerated from',
+    '`data-design-pattern` markers by `sync_design_manifest`. `## Design Decisions` is an',
+    'append-only ADR log written by `record_design_decision`.',
+    '',
+    USAGES_HEADING,
+    '',
+    renderUsagesBlock([]),
+    '',
+    DECISIONS_HEADING,
+    ''
+  ].join('\n');
+}
+
+/** Human-readable context summary for `get_design_context`. */
+export function formatContext(manifest: DesignManifest): string {
+  let md = '# Design Context\n\n';
+
+  const fm = manifest.frontmatter;
+  const keys = Object.keys(fm);
+  if (keys.length > 0) {
+    md += '## Intake\n\n';
+    for (const k of keys) md += `- **${k}:** ${fm[k]}\n`;
+    md += '\n';
+    if (fm.paradigm) {
+      md += `> Stay within the **${fm.paradigm}** paradigm. Call \`get_design_principles(topic="theming")\` for its token profile.\n\n`;
+    }
+  }
+
+  md += '## Pattern Usages\n\n';
+  if (manifest.usages.length === 0) {
+    md +=
+      '_None recorded._ Add `data-design-pattern="<name>"` to page roots, then run `sync_design_manifest`.\n\n';
+  } else {
+    const byPattern = new Map<string, string[]>();
+    for (const u of manifest.usages) {
+      (byPattern.get(u.pattern) ?? byPattern.set(u.pattern, []).get(u.pattern)!).push(u.file);
+    }
+    for (const [pattern, files] of [...byPattern].sort((a, b) => a[0].localeCompare(b[0]))) {
+      md += `- \`${pattern}\` (${files.length}): ${files.join(', ')}\n`;
+    }
+    md += '\n> To change a pattern across the app, migrate every file listed under it.\n\n';
+  }
+
+  md += '## Design Decisions\n\n';
+  if (manifest.decisions.length === 0) {
+    md +=
+      '_None recorded._ Use `record_design_decision` when you deviate from a pattern or principle.\n';
+  } else {
+    for (const d of manifest.decisions) {
+      md += `- **${d.date} — ${d.title}** (${d.status}): ${d.decision}\n`;
+    }
+  }
+  return md;
+}
+
+export { DECISIONS_HEADING, USAGES_END, USAGES_HEADING, USAGES_START };

package/src/design-manifest/scan.test.ts

@@ -0,0 +1,51 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { scanMarkers } from './scan.js';
+
+let root: string;
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'uib-scan-'));
+  const write = async (rel: string, body: string) => {
+    const path = join(root, rel);
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, body, 'utf-8');
+  };
+  await write('src/routes/dashboard/+page.svelte', '<div data-design-pattern="dashboard">…</div>');
+  await write('src/routes/signup/+page.svelte', "<main data-design-pattern='form-page'>…</main>");
+  await write('src/lib/Plain.svelte', '<div class="bg-surface-base">no marker</div>');
+  // Must be skipped:
+  await write('src/node_modules/pkg/Comp.svelte', '<div data-design-pattern="should-skip">…</div>');
+  await write('dist/built.svelte', '<div data-design-pattern="should-skip">…</div>');
+});
+
+afterAll(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+describe('scanMarkers', () => {
+  it('finds markers and reports project-relative paths', async () => {
+    const usages = await scanMarkers(join(root, 'src'), root);
+    const patterns = usages.map((u) => u.pattern).sort();
+    expect(patterns).toEqual(['dashboard', 'form-page']);
+    expect(usages.find((u) => u.pattern === 'dashboard')?.file).toBe(
+      'src/routes/dashboard/+page.svelte'
+    );
+  });
+
+  it('skips node_modules and build output', async () => {
+    const usages = await scanMarkers(root, root);
+    expect(usages.some((u) => u.pattern === 'should-skip')).toBe(false);
+  });
+
+  it('handles both single- and double-quoted markers', async () => {
+    const usages = await scanMarkers(join(root, 'src'), root);
+    expect(usages.some((u) => u.pattern === 'form-page')).toBe(true);
+  });
+
+  it('returns empty for a non-existent directory', async () => {
+    expect(await scanMarkers(join(root, 'does-not-exist'))).toEqual([]);
+  });
+});

package/src/design-manifest/scan.ts

@@ -0,0 +1,74 @@
+/**
+ * Scan a source tree for `data-design-pattern="…"` markers. This is the
+ * convention (analogous to the `data-guide` namespace) that makes pattern usage
+ * greppable instead of guessable — the answer to DESIGN-SYSTEM-INTELLIGENCE.md's
+ * "how does the LLM reliably find which pages follow a pattern?".
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import type { PatternUsage } from './types.js';
+
+const SCANNED_EXT = /\.(svelte|html|tsx|jsx|astro|vue)$/;
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.svelte-kit',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.turbo',
+  'coverage'
+]);
+
+const MARKER_RE = /data-design-pattern\s*=\s*["'`]([a-z0-9-]+)["'`]/g;
+
+/** Recursion cap — guards against symlink loops; real source trees are far shallower. */
+const MAX_DEPTH = 24;
+
+/**
+ * Recursively scan `dir` for marker usages. Files in the returned list are
+ * relative to `baseDir` (default `dir`) so the manifest stays portable.
+ */
+export async function scanMarkers(
+  dir: string,
+  baseDir: string = dir,
+  depth = 0
+): Promise<PatternUsage[]> {
+  const usages: PatternUsage[] = [];
+  if (depth > MAX_DEPTH) return usages;
+
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return usages;
+  }
+
+  for (const name of names) {
+    const full = join(dir, name);
+    const info = await stat(full).catch(() => null);
+    if (!info) continue;
+
+    if (info.isDirectory()) {
+      if (SKIP_DIRS.has(name) || name.startsWith('.')) continue;
+      usages.push(...(await scanMarkers(full, baseDir, depth + 1)));
+    } else if (info.isFile() && SCANNED_EXT.test(name)) {
+      let content: string;
+      try {
+        content = await readFile(full, 'utf-8');
+      } catch {
+        continue;
+      }
+      const seen = new Set<string>();
+      for (const m of content.matchAll(MARKER_RE)) {
+        const pattern = m[1]!;
+        if (seen.has(pattern)) continue; // one entry per (pattern, file)
+        seen.add(pattern);
+        usages.push({ pattern, file: relative(baseDir, full).split(sep).join('/') });
+      }
+    }
+  }
+
+  return usages;
+}

package/src/design-manifest/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Types for the design manifest — the per-consumer-project memory of design
+ * intent (docs/DESIGN-MCP.md, Option C). The manifest is a Markdown file
+ * (`design.manifest.md`) at the consumer's project root with three parts:
+ *
+ *  1. Frontmatter — the enforced intake decisions (paradigm, theme, density).
+ *  2. Pattern Usages — an auto-generated index of `data-design-pattern` markers
+ *     found in the source (so "which pages follow pattern X" is a grep, not a
+ *     guess — answering the open question from DESIGN-SYSTEM-INTELLIGENCE.md).
+ *  3. Design Decisions — append-only ADRs recording deliberate deviations.
+ */
+
+/** One `data-design-pattern="…"` marker found in the source tree. */
+export interface PatternUsage {
+  /** The pattern name, e.g. "dashboard". */
+  pattern: string;
+  /** Source file, relative to the project root. */
+  file: string;
+}
+
+/** A recorded design decision (ADR). */
+export interface DesignDecision {
+  /** ISO date (YYYY-MM-DD). */
+  date: string;
+  title: string;
+  /** accepted | proposed | superseded — free text, defaults to "accepted". */
+  status: string;
+  decision: string;
+  rationale?: string;
+}
+
+/** Parsed view of a manifest file. */
+export interface DesignManifest {
+  /** Flat key→value frontmatter (paradigm, theme, density, …). */
+  frontmatter: Record<string, string>;
+  usages: PatternUsage[];
+  decisions: DesignDecision[];
+  /** Whether a manifest file actually existed (false → defaults returned). */
+  exists: boolean;
+}

package/src/design-rubric/rubric.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { MAX_RUBRIC_SCORE, RUBRIC_CRITERIA, renderRubric } from './rubric.js';
+
+describe('rubric criteria', () => {
+  it('keeps the eight A/B-test criteria', () => {
+    expect(RUBRIC_CRITERIA).toHaveLength(8);
+    expect(MAX_RUBRIC_SCORE).toBe(40);
+  });
+
+  it('has unique ids and complete anchors', () => {
+    const ids = new Set(RUBRIC_CRITERIA.map((c) => c.id));
+    expect(ids.size).toBe(RUBRIC_CRITERIA.length);
+    for (const c of RUBRIC_CRITERIA) {
+      expect(c.name).toBeTruthy();
+      expect(c.measures).toBeTruthy();
+      for (const score of [1, 3, 5] as const) {
+        expect(c.anchors[score], `${c.id} anchor ${score}`).toBeTruthy();
+      }
+    }
+  });
+
+  it('anchors technical correctness on validate_design', () => {
+    const correctness = RUBRIC_CRITERIA.find((c) => c.id === 'correctness');
+    expect(correctness?.anchors[5]).toContain('validate_design');
+  });
+});
+
+describe('renderRubric', () => {
+  const md = renderRubric();
+
+  it('renders every criterion and the total', () => {
+    for (const c of RUBRIC_CRITERIA) expect(md).toContain(c.name);
+    expect(md).toContain(`/${MAX_RUBRIC_SCORE}`);
+  });
+
+  it('tells the judge to run validate_design first', () => {
+    expect(md).toContain('validate_design');
+  });
+
+  it('describes the panel-of-lenses approach for variant selection', () => {
+    expect(md.toLowerCase()).toContain('lens');
+  });
+});