agentready-design-cli 0.1.0

package/dist/chunk-GWF7PSLR.js

@@ -0,0 +1,1207 @@
+#!/usr/bin/env node
+
+// src/rubric.ts
+var RUBRIC = [
+  // Category 1 — Tokens & Foundations
+  { id: "1.1", category: 1, title: "Tokens exist as exported, versioned source files." },
+  { id: "1.2", category: 1, title: "Semantic tokens exist on top of primitives." },
+  { id: "1.3", category: 1, title: "Tokens are closed and enumerable." },
+  { id: "1.4", category: 1, title: "Token usage is enforced." },
+  // Category 2 — Component API Contract
+  { id: "2.1", category: 2, title: "Every component has a machine-readable manifest." },
+  { id: "2.2", category: 2, title: "Prop naming is consistent across the library." },
+  { id: "2.3", category: 2, title: "Composition and slot rules are explicit." },
+  { id: "2.4", category: 2, title: "Anti-patterns are documented per component." },
+  { id: "2.5", category: 2, title: "Accessibility metadata travels with the component." },
+  // Category 3 — Documentation Format
+  { id: "3.1", category: 3, title: "Single canonical docs site, no scattered duplicates." },
+  { id: "3.2", category: 3, title: "Component pages have a stable, predictable structure." },
+  { id: "3.3", category: 3, title: "At least 3 concrete usage examples per component, with anti-patterns." },
+  { id: "3.4", category: 3, title: "An llms.txt (and optionally llms-full.txt) is published." },
+  // Category 4 — Composition & Layout
+  { id: "4.1", category: 4, title: "Layout primitives exist as first-class components." },
+  { id: "4.2", category: 4, title: "Responsive conventions are explicit and uniform." },
+  { id: "4.3", category: 4, title: "A patterns or recipes layer exists for compositions agents should reuse." },
+  // Category 5 — Retrieval & Discoverability
+  { id: "5.1", category: 5, title: "AGENTS.md (or CLAUDE.md) exists and is hand-curated." },
+  { id: "5.2", category: 5, title: "An MCP server (or registry endpoint) exposes the system to agents." },
+  { id: "5.3", category: 5, title: "Always-on foundational rules are injected into every agent run." },
+  { id: "5.4", category: 5, title: "Components are addressable by stable, predictable identifiers." },
+  // Category 6 — Distribution & Versioning
+  { id: "6.1", category: 6, title: "The system is installable through a single, well-known mechanism." },
+  { id: "6.2", category: 6, title: "Breaking changes and deprecations are machine-readable." },
+  { id: "6.3", category: 6, title: "A clear current vs. latest version is communicated to agents." },
+  // Category 7 — Quality Signals
+  { id: "7.1", category: 7, title: "Every component has interaction tests / stories." },
+  { id: "7.2", category: 7, title: "Visual regression is in place." },
+  { id: "7.3", category: 7, title: "Accessibility checks are automated." },
+  { id: "7.4", category: 7, title: "Code quality and consistency within the library itself." },
+  // Category 8 — Evaluation & Governance for Agents
+  { id: "8.1", category: 8, title: "An eval suite tests agent output against the design system." },
+  { id: "8.2", category: 8, title: "Trust levels are defined for agent actions." },
+  { id: "8.3", category: 8, title: "Drift detection between docs, tokens, and code." },
+  { id: "8.4", category: 8, title: "Generated-code attribution and review." }
+];
+var TOTAL_CRITERIA = RUBRIC.length;
+
+// src/rollup.ts
+function median(nums) {
+  if (nums.length === 0) return 0;
+  const sorted = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2 : sorted[mid] ?? 0;
+}
+function scored(criteria) {
+  return criteria.filter((c) => c.status === "scored" && c.score !== null);
+}
+function categoryScores(criteria, category) {
+  return scored(criteria).filter((c) => c.category === category).map((c) => c.score);
+}
+function tierFor(floor, retrieval, overall, byCat) {
+  const cat8Median = byCat["8"] ?? 0;
+  const allCatsAtLeast3 = [1, 2, 3, 4, 5, 6, 7, 8].every((c) => (byCat[String(c)] ?? 0) >= 3);
+  if (allCatsAtLeast3 && cat8Median >= 3) return 4;
+  if (floor >= 3 && retrieval >= 3 && overall >= 3) return 3;
+  if (floor >= 2 && retrieval >= 2 && overall >= 2) return 2;
+  if (floor >= 2) return 1;
+  return 0;
+}
+function computeRollup(criteria) {
+  const foundationalScores = scored(criteria).filter((c) => c.category <= 4).map((c) => c.score);
+  const retrievalScores = categoryScores(criteria, 5);
+  const allScores = scored(criteria).map((c) => c.score);
+  const categoryFloors = {};
+  const categoryMedians = {};
+  for (const cat of [1, 2, 3, 4, 5, 6, 7, 8]) {
+    const s = categoryScores(criteria, cat);
+    if (s.length > 0) {
+      categoryFloors[`${cat}`] = Math.min(...s);
+      categoryMedians[`${cat}`] = median(s);
+    }
+  }
+  const floor = foundationalScores.length > 0 ? Math.min(...foundationalScores) : 0;
+  const retrieval = retrievalScores.length > 0 ? Math.max(...retrievalScores) : 0;
+  const overall = median(allScores);
+  const tier = tierFor(floor, retrieval, overall, categoryMedians);
+  return {
+    foundationalFloor: floor,
+    retrievalLevel: retrieval,
+    overallMedian: overall,
+    tier,
+    categoryFloors,
+    categoryMedians
+  };
+}
+var TIER_LABELS = {
+  0: "Pre-agentic",
+  1: "Human-ready, AI-hostile",
+  2: "Agent-legible",
+  3: "Agent-collaborative",
+  4: "Self-healing"
+};
+var EFFORT_HINTS = {
+  "1.1": "days",
+  "1.2": "days",
+  "1.3": "days",
+  "1.4": "hours",
+  "2.1": "weeks",
+  "2.2": "weeks",
+  "2.3": "weeks",
+  "2.4": "days",
+  "2.5": "weeks",
+  "3.1": "weeks",
+  "3.2": "weeks",
+  "3.3": "weeks",
+  "3.4": "hours",
+  "4.1": "weeks",
+  "4.2": "days",
+  "4.3": "weeks",
+  "5.1": "hours",
+  "5.2": "weeks",
+  "5.3": "hours",
+  "5.4": "days",
+  "6.1": "weeks",
+  "6.2": "days",
+  "6.3": "hours",
+  "7.1": "weeks",
+  "7.2": "days",
+  "7.3": "days",
+  "7.4": "weeks",
+  "8.1": "months",
+  "8.2": "days",
+  "8.3": "weeks",
+  "8.4": "days"
+};
+function generateBacklog(criteria) {
+  const ranked = [...criteria].filter((c) => c.score !== null && c.score < 3).sort((a, b) => {
+    const aFoundational = a.category <= 4 ? 0 : 1;
+    const bFoundational = b.category <= 4 ? 0 : 1;
+    if (aFoundational !== bFoundational) return aFoundational - bFoundational;
+    const aScore = a.score ?? 0;
+    const bScore = b.score ?? 0;
+    if (aScore !== bScore) return aScore - bScore;
+    return a.category - b.category;
+  }).slice(0, 10);
+  return ranked.map((c, i) => ({
+    title: c.suggestion ?? `Raise ${c.id} from ${c.score}/4 toward 3+`,
+    rationale: c.rationale ?? `Criterion ${c.id} is at ${c.score}/4.`,
+    criteria: [c.id],
+    priority: i + 1,
+    estimatedEffort: EFFORT_HINTS[c.id] ?? "days"
+  }));
+}
+
+// src/context.ts
+import { readFile, stat } from "fs/promises";
+import { resolve, relative, sep } from "path";
+import fg from "fast-glob";
+var IGNORES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/.astro/**",
+  "**/.cache/**",
+  "**/.turbo/**",
+  "**/coverage/**",
+  "**/.git/**"
+];
+var CheckContext = class {
+  root;
+  fileCache = /* @__PURE__ */ new Map();
+  globCache = /* @__PURE__ */ new Map();
+  pkgJsonCache;
+  constructor(root) {
+    this.root = resolve(root);
+  }
+  resolve(...p) {
+    return resolve(this.root, ...p);
+  }
+  relative(p) {
+    return relative(this.root, p).split(sep).join("/");
+  }
+  async exists(rel) {
+    try {
+      await stat(this.resolve(rel));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async existsAny(rels) {
+    for (const r of rels) {
+      if (await this.exists(r)) return r;
+    }
+    return null;
+  }
+  async readFile(rel) {
+    if (this.fileCache.has(rel)) return this.fileCache.get(rel) ?? null;
+    try {
+      const content = await readFile(this.resolve(rel), "utf8");
+      this.fileCache.set(rel, content);
+      return content;
+    } catch {
+      this.fileCache.set(rel, null);
+      return null;
+    }
+  }
+  async glob(pattern, opts) {
+    const key = JSON.stringify({ p: pattern, i: opts?.ignore ?? null });
+    const cached = this.globCache.get(key);
+    if (cached) return cached;
+    const matches = await fg(pattern, {
+      cwd: this.root,
+      ignore: [...IGNORES, ...opts?.ignore ?? []],
+      dot: true,
+      onlyFiles: true,
+      followSymbolicLinks: false
+    });
+    matches.sort();
+    this.globCache.set(key, matches);
+    return matches;
+  }
+  async firstMatch(pattern) {
+    const matches = await this.glob(pattern);
+    return matches[0] ?? null;
+  }
+  async pkgJson() {
+    if (this.pkgJsonCache !== void 0) return this.pkgJsonCache;
+    const raw = await this.readFile("package.json");
+    if (!raw) {
+      this.pkgJsonCache = null;
+      return null;
+    }
+    try {
+      this.pkgJsonCache = JSON.parse(raw);
+    } catch {
+      this.pkgJsonCache = null;
+    }
+    return this.pkgJsonCache;
+  }
+  /**
+   * Heuristic "component directories" — places to look for component source.
+   * Covers common conventions: top-level components/, ui/, lib/, src/, packages/*\/src.
+   */
+  async componentDirs() {
+    const candidates = [
+      "components",
+      "src/components",
+      "src/ui",
+      "ui",
+      "lib/components",
+      "packages/ui/src",
+      "packages/components/src",
+      "packages/ui/src/components"
+    ];
+    const found = [];
+    for (const c of candidates) {
+      if (await this.exists(c)) found.push(c);
+    }
+    if (found.length === 0) {
+      const pkgs = await this.glob("packages/*/package.json");
+      for (const p of pkgs) {
+        const base = p.replace(/\/package\.json$/, "");
+        for (const sub of ["src", "src/components", "components"]) {
+          const full = `${base}/${sub}`;
+          if (await this.exists(full)) found.push(full);
+        }
+      }
+    }
+    return found;
+  }
+};
+
+// src/checks/category-1-tokens.ts
+var TOKEN_DIRS = ["tokens", "src/tokens", "design-tokens", "src/design-tokens", "packages/tokens"];
+async function findTokenSources(ctx) {
+  const out = {
+    dir: null,
+    jsonFiles: [],
+    cssVarFiles: [],
+    dtcg: false,
+    styleDictionary: false
+  };
+  for (const d of TOKEN_DIRS) {
+    if (await ctx.exists(d)) {
+      out.dir = d;
+      break;
+    }
+  }
+  out.jsonFiles = await ctx.glob([
+    "tokens/**/*.json",
+    "**/*.tokens.json",
+    "design-tokens/**/*.json",
+    "packages/tokens/**/*.json"
+  ]);
+  out.cssVarFiles = await ctx.glob(["tokens/**/*.{css,scss}", "src/tokens/**/*.{css,scss}", "**/tokens.css"]);
+  if (await ctx.firstMatch(["style-dictionary.config.{js,cjs,mjs,ts,json}", "sd.config.{js,cjs,mjs,ts,json}"])) {
+    out.styleDictionary = true;
+  }
+  for (const f of out.jsonFiles.slice(0, 5)) {
+    const raw = await ctx.readFile(f);
+    if (raw && /"\$value"\s*:/.test(raw)) {
+      out.dtcg = true;
+      break;
+    }
+  }
+  return out;
+}
+var checks = {
+  "1.1": async (ctx) => {
+    const t = await findTokenSources(ctx);
+    if (!t.dir && t.jsonFiles.length === 0 && t.cssVarFiles.length === 0) {
+      return {
+        score: 0,
+        rationale: "No token directory, JSON token export, or CSS-variables file detected.",
+        evidence: [
+          { kind: "glob", path: TOKEN_DIRS.join(", "), detail: "no matches" },
+          { kind: "glob", path: "**/*.tokens.json", detail: "no matches" }
+        ],
+        suggestion: "Create a /tokens directory and export tokens as JSON or CSS custom properties."
+      };
+    }
+    if (t.dtcg && t.styleDictionary) {
+      return {
+        score: 4,
+        rationale: "DTCG-formatted JSON tokens detected alongside a Style Dictionary build pipeline.",
+        evidence: [
+          ...t.dir ? [{ kind: "file", path: t.dir }] : [],
+          ...t.jsonFiles.slice(0, 3).map((f) => ({ kind: "file", path: f })),
+          { kind: "note", detail: "Style Dictionary config present" }
+        ]
+      };
+    }
+    if (t.dtcg) {
+      return {
+        score: 3,
+        rationale: "DTCG-formatted JSON tokens detected (uses $value/$type).",
+        evidence: t.jsonFiles.slice(0, 5).map((f) => ({ kind: "file", path: f })),
+        suggestion: "Wire up Style Dictionary v4 (or equivalent) to consume the DTCG source."
+      };
+    }
+    if (t.jsonFiles.length > 0) {
+      return {
+        score: 2,
+        rationale: "JSON token export exists but not in DTCG format ($value/$type missing).",
+        evidence: t.jsonFiles.slice(0, 5).map((f) => ({ kind: "file", path: f })),
+        suggestion: "Migrate to W3C DTCG format (stable spec 2025.10)."
+      };
+    }
+    return {
+      score: 1,
+      rationale: "CSS variables exist but no JSON export of the token set.",
+      evidence: t.cssVarFiles.slice(0, 5).map((f) => ({ kind: "file", path: f })),
+      suggestion: "Export tokens as JSON (W3C DTCG format) so agents and tooling can enumerate them."
+    };
+  },
+  "1.2": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Detecting whether semantic tokens layer on top of primitives requires reading token names and component usage; agent should verify."
+  }),
+  "1.3": async (ctx) => {
+    const t = await findTokenSources(ctx);
+    if (t.jsonFiles.length === 0 && t.cssVarFiles.length === 0) {
+      return {
+        score: 0,
+        rationale: "No enumerable token source found.",
+        evidence: [{ kind: "note", detail: "no token JSON or CSS-var files" }]
+      };
+    }
+    return {
+      score: null,
+      status: "pending",
+      pending: "requires-agent",
+      rationale: "Token sources exist; an agent must verify they are exhaustive and that no hidden tokens live in per-component CSS.",
+      evidence: [...t.jsonFiles, ...t.cssVarFiles].slice(0, 5).map((f) => ({ kind: "file", path: f }))
+    };
+  },
+  "1.4": async (ctx) => {
+    const stylelint = await ctx.firstMatch([
+      ".stylelintrc",
+      ".stylelintrc.{json,js,cjs,mjs,yaml,yml}",
+      "stylelint.config.{js,cjs,mjs,ts}"
+    ]);
+    const eslint = await ctx.firstMatch([
+      ".eslintrc",
+      ".eslintrc.{json,js,cjs,mjs,yaml,yml}",
+      "eslint.config.{js,cjs,mjs,ts}"
+    ]);
+    const compDirs = await ctx.componentDirs();
+    const cssFiles = await ctx.glob(compDirs.map((d) => `${d}/**/*.{css,scss}`));
+    const hexFindings = [];
+    for (const f of cssFiles.slice(0, 50)) {
+      const content = await ctx.readFile(f);
+      if (content && /#[0-9a-fA-F]{3,8}\b/.test(content)) {
+        hexFindings.push(f);
+      }
+    }
+    if (!stylelint && hexFindings.length > 0) {
+      return {
+        score: 0,
+        rationale: `No stylelint config detected and ${hexFindings.length} component CSS file(s) contain raw hex literals.`,
+        evidence: hexFindings.slice(0, 5).map((f) => ({ kind: "file", path: f })),
+        suggestion: "Add a stylelint rule that rejects hex literals in component CSS."
+      };
+    }
+    if (!stylelint) {
+      return {
+        score: 1,
+        rationale: "No stylelint config detected; token usage is not enforced by lint.",
+        evidence: [{ kind: "note", detail: "no .stylelintrc / stylelint.config.* found" }],
+        suggestion: "Add stylelint + a rule rejecting raw hex/px in component CSS."
+      };
+    }
+    return {
+      score: null,
+      status: "pending",
+      pending: "requires-agent",
+      rationale: "Stylelint or ESLint config detected; agent should verify it actually rejects raw hex/px in component CSS.",
+      evidence: [
+        ...stylelint ? [{ kind: "file", path: stylelint }] : [],
+        ...eslint ? [{ kind: "file", path: eslint }] : []
+      ]
+    };
+  }
+};
+
+// src/checks/category-2-api.ts
+var checks2 = {
+  "2.1": async (ctx) => {
+    const pkg = await ctx.pkgJson();
+    const declaresCEM = !!pkg && typeof pkg.customElements === "string";
+    const cemFile = await ctx.firstMatch(["custom-elements.json", "**/custom-elements.json"]);
+    const sbManifest = await ctx.firstMatch([
+      "**/manifest/components.json",
+      "**/storybook-manifest.json",
+      ".storybook/manifest.json"
+    ]);
+    const docgen = await ctx.firstMatch(["**/docgen.json", "**/.docgen/**/*.json"]);
+    const enumeratedHint = await (async () => {
+      const files = await ctx.glob(["**/*.{ts,tsx}"], { ignore: ["**/*.test.*", "**/*.stories.*"] });
+      let withEnum = 0;
+      for (const f of files.slice(0, 50)) {
+        const content = await ctx.readFile(f);
+        if (content && /variant\?:\s*["'][^"']+["']\s*\|/.test(content)) withEnum++;
+      }
+      return withEnum;
+    })();
+    if (declaresCEM && cemFile) {
+      return {
+        score: 3,
+        rationale: 'package.json declares "customElements" and a custom-elements.json ships.',
+        evidence: [
+          { kind: "file", path: "package.json", detail: "customElements declared" },
+          { kind: "file", path: cemFile }
+        ],
+        suggestion: "Serve the CEM via an MCP tool to reach Level 4."
+      };
+    }
+    if (cemFile || sbManifest) {
+      return {
+        score: 2,
+        rationale: "Manifest file present but not declared from package.json.",
+        evidence: [
+          ...cemFile ? [{ kind: "file", path: cemFile }] : [],
+          ...sbManifest ? [{ kind: "file", path: sbManifest }] : []
+        ],
+        suggestion: 'Declare "customElements": "custom-elements.json" in package.json and include it in the "files" array.'
+      };
+    }
+    if (docgen) {
+      return {
+        score: 1,
+        rationale: "react-docgen output exists but is not published as a contract.",
+        evidence: [{ kind: "file", path: docgen }],
+        suggestion: "Promote to a versioned component manifest (CEM or Storybook Component Manifest)."
+      };
+    }
+    if (enumeratedHint > 0) {
+      return {
+        score: 1,
+        rationale: "TypeScript types describe component props but no machine-readable manifest is published.",
+        evidence: [{ kind: "note", detail: `${enumeratedHint} component(s) appear to enumerate variants in TS` }],
+        suggestion: "Generate a Custom Elements Manifest or Storybook Component Manifest and ship it in the package."
+      };
+    }
+    return {
+      score: 0,
+      rationale: "No component manifest detected (CEM, Storybook manifest, or react-docgen output).",
+      evidence: [
+        { kind: "glob", path: "custom-elements.json", detail: "no match" },
+        { kind: "glob", path: "**/storybook-manifest.json", detail: "no match" }
+      ],
+      suggestion: "Add a manifest (CEM via @custom-elements-manifest/analyzer is the lowest-friction path)."
+    };
+  },
+  "2.2": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Cross-component prop naming consistency requires reading every component signature; agent should evaluate."
+  }),
+  "2.3": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Whether compound-component composition rules are documented requires reading component docs."
+  }),
+  "2.4": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Anti-pattern presence per component requires reading each component's docs."
+  }),
+  "2.5": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Whether a11y metadata is structured (vs. prose) requires reading docs and/or the manifest."
+  })
+};
+
+// src/checks/category-3-docs.ts
+var checks3 = {
+  "3.1": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Detecting scattered/duplicate docs (Confluence vs Figma vs Storybook) requires external knowledge."
+  }),
+  "3.2": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Structural consistency of docs pages requires reading and comparing MDX/HTML across components."
+  }),
+  "3.3": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Counting per-component examples and identifying anti-patterns requires reading docs."
+  }),
+  "3.4": async (ctx) => {
+    const llmsTxt = await ctx.existsAny(["llms.txt", "public/llms.txt", "site/public/llms.txt", "docs/public/llms.txt"]);
+    const llmsFull = await ctx.existsAny([
+      "llms-full.txt",
+      "public/llms-full.txt",
+      "site/public/llms-full.txt",
+      "docs/public/llms-full.txt"
+    ]);
+    if (!llmsTxt && !llmsFull) {
+      return {
+        score: 0,
+        rationale: "No llms.txt or llms-full.txt found.",
+        evidence: [{ kind: "glob", path: "**/llms*.txt", detail: "no matches" }],
+        suggestion: "Publish /llms.txt at the docs root, per llmstxt.org spec. Look at Cloudscape, Nord, or CMS Design System for examples."
+      };
+    }
+    if (llmsTxt && llmsFull) {
+      return {
+        score: 3,
+        rationale: "Both llms.txt and llms-full.txt are published.",
+        evidence: [
+          { kind: "file", path: llmsTxt },
+          { kind: "file", path: llmsFull }
+        ]
+      };
+    }
+    return {
+      score: 2,
+      rationale: `${llmsTxt ?? llmsFull} is published; the companion file is not.`,
+      evidence: [{ kind: "file", path: llmsTxt ?? llmsFull }],
+      suggestion: "Publish llms-full.txt with per-page Markdown reference content."
+    };
+  }
+};
+
+// src/checks/category-4-composition.ts
+var PRIMITIVE_NAMES = ["Stack", "Inline", "HStack", "VStack", "Grid", "Box", "Container", "Flex", "Cluster"];
+var checks4 = {
+  "4.1": async (ctx) => {
+    const compDirs = await ctx.componentDirs();
+    if (compDirs.length === 0) {
+      return {
+        score: 0,
+        rationale: "Could not locate a components directory; cannot detect layout primitives.",
+        evidence: [{ kind: "note", detail: "no components/, src/components/, ui/, or packages/*/src found" }]
+      };
+    }
+    const found = /* @__PURE__ */ new Set();
+    const filePaths = /* @__PURE__ */ new Map();
+    for (const dir of compDirs) {
+      for (const name of PRIMITIVE_NAMES) {
+        const matches = await ctx.glob([
+          `${dir}/${name}.{ts,tsx,jsx,js,vue,svelte}`,
+          `${dir}/${name}/index.{ts,tsx,jsx,js,vue,svelte}`,
+          `${dir}/${name.toLowerCase()}.{ts,tsx,jsx,js,vue,svelte}`,
+          `${dir}/${name.toLowerCase()}/index.{ts,tsx,jsx,js,vue,svelte}`
+        ]);
+        if (matches.length > 0) {
+          found.add(name);
+          if (!filePaths.has(name)) filePaths.set(name, matches[0]);
+        }
+      }
+    }
+    if (found.size === 0) {
+      return {
+        score: 0,
+        rationale: "No layout primitives (Stack, Inline, Grid, Box, Container) detected.",
+        evidence: [{ kind: "note", detail: `searched: ${compDirs.join(", ")}` }],
+        suggestion: 'Introduce named layout primitives so agents can avoid raw <div className="flex">.'
+      };
+    }
+    const score = found.size >= 3 ? 2 : 1;
+    return {
+      score,
+      rationale: `Found ${found.size} layout primitive(s): ${[...found].join(", ")}.`,
+      evidence: [...filePaths.entries()].slice(0, 5).map(([, path]) => ({ kind: "file", path })),
+      suggestion: score < 2 ? "Add the rest of the standard set (Stack/Inline/Grid/Box/Container)." : "Document the primitives in your manifest so agents pick them over raw divs."
+    };
+  },
+  "4.2": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Whether responsive conventions are uniform requires reading multiple components."
+  }),
+  "4.3": async (ctx) => {
+    const dirs = ["patterns", "recipes", "src/patterns", "src/recipes", "packages/patterns", "packages/recipes"];
+    const found = await ctx.existsAny(dirs);
+    if (!found) {
+      return {
+        score: 0,
+        rationale: "No patterns/ or recipes/ directory detected.",
+        evidence: [{ kind: "glob", path: dirs.join(", "), detail: "no matches" }],
+        suggestion: "Create a recipes/ layer with pre-blessed compositions (EmptyState, DataTableToolbar, ...)."
+      };
+    }
+    return {
+      score: 2,
+      rationale: `A recipes/patterns directory exists: ${found}.`,
+      evidence: [{ kind: "file", path: found }],
+      suggestion: "Add manifests for each recipe and serve via MCP/registry to reach Level 3+."
+    };
+  }
+};
+
+// src/checks/category-5-retrieval.ts
+var AGENT_FILE_CANDIDATES = ["AGENTS.md", ".builder/AGENTS.md", "CLAUDE.md"];
+var RULES_FILES = [".cursorrules", ".cursor/rules", ".windsurfrules", ".clinerules", ".roorules", ".aider.conf.yml"];
+var checks5 = {
+  "5.1": async (ctx) => {
+    const found = [];
+    for (const f of AGENT_FILE_CANDIDATES) {
+      if (await ctx.exists(f)) found.push(f);
+    }
+    if (found.length === 0) {
+      return {
+        score: 0,
+        rationale: "No AGENTS.md or CLAUDE.md found at the repo root.",
+        evidence: [{ kind: "glob", path: AGENT_FILE_CANDIDATES.join(", "), detail: "no matches" }],
+        suggestion: "Write a hand-curated AGENTS.md (per agents.md format) \u2014 canonical import path, anti-hallucination rule, always-on token rules."
+      };
+    }
+    const primary = found[0];
+    const content = await ctx.readFile(primary) ?? "";
+    const looksGeneric = /generated by/i.test(content) || /this file was automatically/i.test(content) || content.length < 300;
+    if (looksGeneric) {
+      return {
+        score: 1,
+        rationale: `${primary} exists but looks auto-generated or minimal (${content.length} chars).`,
+        evidence: [{ kind: "file", path: primary }],
+        suggestion: "Hand-curate AGENTS.md: per ETH Zurich evidence, auto-generated ones reduce task success ~3%."
+      };
+    }
+    return {
+      score: null,
+      status: "pending",
+      pending: "requires-agent",
+      rationale: `${primary} exists; agent should verify it includes canonical import path, anti-hallucination rule, and trust levels.`,
+      evidence: found.map((f) => ({ kind: "file", path: f }))
+    };
+  },
+  "5.2": async (ctx) => {
+    const mcpHints = [];
+    const pkg = await ctx.pkgJson();
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const mcpDeps = Object.keys(deps ?? {}).filter((k) => /mcp/i.test(k) || /modelcontext/i.test(k));
+    if (mcpDeps.length > 0) mcpHints.push(`deps: ${mcpDeps.join(", ")}`);
+    const registry = await ctx.firstMatch(["registry.json", "**/registry.json"]);
+    const sbConfig = await ctx.firstMatch([".storybook/main.{ts,tsx,js,cjs,mjs}"]);
+    if (sbConfig) {
+      const c = await ctx.readFile(sbConfig) ?? "";
+      if (/storybook.*mcp|@storybook\/.+mcp/i.test(c)) mcpHints.push(`Storybook MCP addon referenced in ${sbConfig}`);
+    }
+    const customMcp = await ctx.firstMatch(["mcp-server/**/*.{ts,js}", "mcp/**/*.{ts,js}", "scripts/mcp-server.{ts,js,mjs}"]);
+    if (customMcp) mcpHints.push(`custom MCP server: ${customMcp}`);
+    if (mcpHints.length === 0 && !registry) {
+      return {
+        score: 0,
+        rationale: "No MCP server, registry endpoint, or MCP-related dependency detected.",
+        evidence: [{ kind: "note", detail: "checked package.json deps, registry.json, Storybook MCP addon, mcp-server/" }],
+        suggestion: "Lowest-friction options: Storybook 10.3+ MCP addon, `npx shadcn registry:mcp`, or a custom MCP wrapping your component manifest."
+      };
+    }
+    if (registry && mcpHints.length > 0) {
+      return {
+        score: 3,
+        rationale: `Registry endpoint and MCP indicators both present.`,
+        evidence: [{ kind: "file", path: registry }, ...mcpHints.map((h) => ({ kind: "note", detail: h }))],
+        suggestion: "Confirm the MCP is hosted, authenticated, versioned, and returns curated (not raw) responses."
+      };
+    }
+    if (registry) {
+      return {
+        score: 2,
+        rationale: `shadcn-style registry endpoint detected: ${registry}.`,
+        evidence: [{ kind: "file", path: registry }],
+        suggestion: "Expose the registry via `npx shadcn registry:mcp` so MCP-aware agents can register it."
+      };
+    }
+    return {
+      score: 1,
+      rationale: `MCP-related artifacts detected but no published endpoint confirmed: ${mcpHints.join("; ")}.`,
+      evidence: mcpHints.map((h) => ({ kind: "note", detail: h })),
+      suggestion: "Host the MCP (Chromatic's Storybook MCP auto-publish is one-click) and add its URL to AGENTS.md."
+    };
+  },
+  "5.3": async (ctx) => {
+    const presentRules = [];
+    for (const r of RULES_FILES) {
+      if (await ctx.exists(r)) presentRules.push(r);
+    }
+    if (presentRules.length === 0) {
+      return {
+        score: 0,
+        rationale: "No agent-rules file (.cursorrules, .windsurfrules, etc.) and no AGENTS.md detected.",
+        evidence: [{ kind: "glob", path: RULES_FILES.join(", "), detail: "no matches" }],
+        suggestion: "Per Brad Frost's progressive disclosure: put foundations (spacing/color/type) in always-on rules, not behind MCP."
+      };
+    }
+    return {
+      score: null,
+      status: "pending",
+      pending: "requires-agent",
+      rationale: `Rules file(s) detected (${presentRules.join(", ")}); agent should verify they include token/foundation rules, not just generic instructions.`,
+      evidence: presentRules.map((f) => ({ kind: "file", path: f }))
+    };
+  },
+  "5.4": async (ctx) => {
+    const pkg = await ctx.pkgJson();
+    if (!pkg) {
+      return {
+        score: 0,
+        rationale: "No package.json at root \u2014 cannot determine canonical import path.",
+        evidence: [{ kind: "note", detail: "package.json missing" }]
+      };
+    }
+    const exports = pkg.exports;
+    if (exports && typeof exports === "object") {
+      return {
+        score: 2,
+        rationale: 'package.json declares an "exports" map; subpath imports are likely stable.',
+        evidence: [{ kind: "file", path: "package.json", detail: "exports field declared" }],
+        suggestion: "Document the canonical import path in AGENTS.md so agents do not guess."
+      };
+    }
+    return {
+      score: 1,
+      rationale: 'package.json has no "exports" map; subpath imports are ad hoc.',
+      evidence: [{ kind: "file", path: "package.json", detail: "no exports field" }],
+      suggestion: 'Add an "exports" map and document canonical paths in AGENTS.md.'
+    };
+  }
+};
+
+// src/checks/category-6-distribution.ts
+var SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.+-]+)?$/;
+var checks6 = {
+  "6.1": async (ctx) => {
+    const pkg = await ctx.pkgJson();
+    const registry = await ctx.firstMatch(["registry.json", "**/registry.json"]);
+    if (!pkg && !registry) {
+      return {
+        score: 0,
+        rationale: "No root package.json and no registry.json \u2014 installation path unclear.",
+        evidence: [{ kind: "note", detail: "neither package.json nor registry.json found" }],
+        suggestion: "Publish as an npm package or adopt the shadcn registry pattern."
+      };
+    }
+    const hints = [];
+    if (pkg?.name && pkg.private !== true) hints.push(`npm package: ${String(pkg.name)}`);
+    if (registry) hints.push(`registry: ${registry}`);
+    if (pkg?.workspaces) hints.push("monorepo workspaces");
+    const score = hints.length >= 2 ? 3 : 2;
+    return {
+      score,
+      rationale: hints.join("; "),
+      evidence: [
+        ...pkg ? [{ kind: "file", path: "package.json" }] : [],
+        ...registry ? [{ kind: "file", path: registry }] : []
+      ],
+      suggestion: score < 3 ? "Combine a versioned npm package with a registry endpoint for AI tooling." : void 0
+    };
+  },
+  "6.2": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Detecting structured deprecation (manifest `deprecated: true`) requires reading the manifest contents; agent should verify."
+  }),
+  "6.3": async (ctx) => {
+    const pkg = await ctx.pkgJson();
+    const hasSemver = !!pkg?.version && SEMVER_RE.test(String(pkg.version));
+    const agentsContent = await ctx.readFile("AGENTS.md") ?? await ctx.readFile("CLAUDE.md") ?? "";
+    const mentionsVersion = /version|`v\d+\.\d+`|@\w+\/.+@/i.test(agentsContent);
+    if (!hasSemver && !mentionsVersion) {
+      return {
+        score: 0,
+        rationale: "No semver version in package.json and no version reference in AGENTS.md/CLAUDE.md.",
+        evidence: [{ kind: "note", detail: "version contract not communicated" }],
+        suggestion: "Pin a semver version in package.json and document the target version in AGENTS.md."
+      };
+    }
+    if (hasSemver && mentionsVersion) {
+      return {
+        score: 2,
+        rationale: "Semver version present and AGENTS.md mentions a version target.",
+        evidence: [
+          { kind: "file", path: "package.json", detail: `version ${String(pkg?.version)}` }
+        ]
+      };
+    }
+    return {
+      score: 1,
+      rationale: hasSemver ? "Semver version present but AGENTS.md does not state which version agents should target." : "AGENTS.md mentions versioning but package.json lacks a semver value.",
+      evidence: [
+        ...hasSemver ? [{ kind: "file", path: "package.json", detail: `version ${String(pkg?.version)}` }] : []
+      ],
+      suggestion: hasSemver ? "Add a 'system-version' note to AGENTS.md telling agents to check package.json." : "Pin a semver version (1.0.0+) in package.json."
+    };
+  }
+};
+
+// src/checks/category-7-quality.ts
+var RAW_HTML_TAGS = ["button", "input", "select", "textarea"];
+var checks7 = {
+  "7.1": async (ctx) => {
+    const stories = await ctx.glob(["**/*.stories.{ts,tsx,js,jsx,mdx}"]);
+    const tests = await ctx.glob(["**/*.{test,spec}.{ts,tsx,js,jsx}"]);
+    const storybookConfig = await ctx.firstMatch([".storybook/main.{ts,tsx,js,cjs,mjs}"]);
+    if (stories.length === 0 && tests.length === 0) {
+      return {
+        score: 0,
+        rationale: "No stories or test files found.",
+        evidence: [
+          { kind: "glob", path: "**/*.stories.*", detail: "no matches" },
+          { kind: "glob", path: "**/*.test.*", detail: "no matches" }
+        ],
+        suggestion: "Add Storybook stories or Vitest/Jest tests covering each component's variants."
+      };
+    }
+    const score = stories.length > 0 && tests.length > 0 ? 3 : storybookConfig ? 2 : 1;
+    return {
+      score,
+      rationale: `Found ${stories.length} stories and ${tests.length} test files${storybookConfig ? " with Storybook configured" : ""}.`,
+      evidence: [
+        ...storybookConfig ? [{ kind: "file", path: storybookConfig }] : [],
+        ...stories.slice(0, 3).map((f) => ({ kind: "file", path: f }))
+      ],
+      suggestion: score < 3 ? "Combine stories with interaction tests (play functions) to reach Level 3." : void 0
+    };
+  },
+  "7.2": async (ctx) => {
+    const pkg = await ctx.pkgJson();
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const vrTools = ["@chromatic-com/storybook", "chromatic", "@percy/cli", "loki", "lost-pixel", "@playwright/test"];
+    const found = vrTools.filter((t) => Object.prototype.hasOwnProperty.call(deps ?? {}, t));
+    const chromaticConfig = await ctx.firstMatch(["chromatic.config.json", ".chromatic.json"]);
+    if (found.length === 0 && !chromaticConfig) {
+      return {
+        score: 0,
+        rationale: "No visual-regression tooling (Chromatic, Percy, Loki, Lost Pixel, Playwright) detected.",
+        evidence: [{ kind: "note", detail: "no matching deps or config" }],
+        suggestion: "Add Chromatic (one-click for Storybook) or Lost Pixel for OSS."
+      };
+    }
+    return {
+      score: 2,
+      rationale: `Visual-regression tooling detected: ${found.join(", ") || chromaticConfig}.`,
+      evidence: [
+        ...chromaticConfig ? [{ kind: "file", path: chromaticConfig }] : [],
+        { kind: "file", path: "package.json", detail: found.join(", ") || "" }
+      ],
+      suggestion: "Wire visual regression into the agent codegen loop (auto-screenshot, diff against baseline)."
+    };
+  },
+  "7.3": async (ctx) => {
+    const pkg = await ctx.pkgJson();
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const a11yTools = ["axe-core", "@axe-core/react", "@axe-core/playwright", "jest-axe", "@storybook/addon-a11y", "vitest-axe"];
+    const found = a11yTools.filter((t) => Object.prototype.hasOwnProperty.call(deps ?? {}, t));
+    if (found.length === 0) {
+      return {
+        score: 0,
+        rationale: "No automated accessibility tooling detected.",
+        evidence: [{ kind: "note", detail: "axe / lighthouse / a11y addon not found" }],
+        suggestion: "Add @storybook/addon-a11y and run axe on stories in CI."
+      };
+    }
+    return {
+      score: 2,
+      rationale: `A11y tooling detected: ${found.join(", ")}.`,
+      evidence: [{ kind: "file", path: "package.json", detail: found.join(", ") }],
+      suggestion: "Gate CI on a11y failures and expose the check via MCP for agent-generated UI."
+    };
+  },
+  "7.4": async (ctx) => {
+    const compDirs = await ctx.componentDirs();
+    if (compDirs.length === 0) {
+      return {
+        score: null,
+        status: "pending",
+        pending: "requires-agent",
+        rationale: "No components/ directory detected to scan for raw HTML or hex literals."
+      };
+    }
+    const sources = await ctx.glob(compDirs.map((d) => `${d}/**/*.{ts,tsx,jsx,vue,svelte}`));
+    let rawHtmlHits = 0;
+    let hexInCss = 0;
+    const sampleRawHtml = [];
+    const sampleHex = [];
+    const tagRe = new RegExp(`<(${RAW_HTML_TAGS.join("|")})(\\s|>|/)`);
+    for (const f of sources.slice(0, 100)) {
+      const content = await ctx.readFile(f);
+      if (content && tagRe.test(content)) {
+        rawHtmlHits++;
+        if (sampleRawHtml.length < 3) sampleRawHtml.push(f);
+      }
+    }
+    const cssFiles = await ctx.glob(compDirs.map((d) => `${d}/**/*.{css,scss}`));
+    for (const f of cssFiles.slice(0, 50)) {
+      const content = await ctx.readFile(f);
+      if (content && /#[0-9a-fA-F]{3,8}\b/.test(content)) {
+        hexInCss++;
+        if (sampleHex.length < 3) sampleHex.push(f);
+      }
+    }
+    if (rawHtmlHits === 0 && hexInCss === 0) {
+      return {
+        score: 3,
+        rationale: "No raw <button>/<input> or hex literals detected in scanned component sources.",
+        evidence: [{ kind: "note", detail: `scanned ${sources.length} component files across ${compDirs.length} dir(s)` }]
+      };
+    }
+    const score = rawHtmlHits + hexInCss > 10 ? 0 : rawHtmlHits + hexInCss > 3 ? 1 : 2;
+    return {
+      score,
+      rationale: `${rawHtmlHits} component file(s) use raw <button>/<input>/etc.; ${hexInCss} component CSS file(s) contain hex literals.`,
+      evidence: [
+        ...sampleRawHtml.map((p) => ({ kind: "file", path: p, detail: "raw HTML tag" })),
+        ...sampleHex.map((p) => ({ kind: "file", path: p, detail: "hex literal" }))
+      ],
+      suggestion: "Replace raw HTML with library primitives and move colors to tokens."
+    };
+  }
+};
+
+// src/checks/category-8-evaluation.ts
+var checks8 = {
+  "8.1": async (ctx) => {
+    const candidates = ["evals", "evaluation", "eval", "agent-evals", "tests/evals"];
+    const found = await ctx.existsAny(candidates);
+    if (!found) {
+      return {
+        score: 0,
+        rationale: "No evals/ or evaluation/ directory detected.",
+        evidence: [{ kind: "glob", path: candidates.join(", "), detail: "no matches" }],
+        suggestion: "Build an Indeed-style eval harness: a fixed prompt set scored on real-component imports + token compliance + LLM-as-judge."
+      };
+    }
+    return {
+      score: null,
+      status: "pending",
+      pending: "requires-agent",
+      rationale: `An evals directory exists (${found}); agent should verify it actually scores agent output against the design system.`,
+      evidence: [{ kind: "file", path: found }]
+    };
+  },
+  "8.2": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Trust levels for agent actions live in AGENTS.md and CI config; agent should verify the policy is encoded."
+  }),
+  "8.3": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Drift detection between docs/tokens/code is a CI check; agent should verify it exists."
+  }),
+  "8.4": async () => ({
+    score: null,
+    status: "pending",
+    pending: "requires-agent",
+    rationale: "Agent-PR labeling and review routing is a process question; agent should ask or inspect CODEOWNERS / labeler.yml."
+  })
+};
+
+// src/checks/index.ts
+var allChecks = {
+  ...checks,
+  ...checks2,
+  ...checks3,
+  ...checks4,
+  ...checks5,
+  ...checks6,
+  ...checks7,
+  ...checks8
+};
+
+// src/runner.ts
+import { readFile as readFile2 } from "fs/promises";
+async function runAssessment(opts) {
+  const ctx = new CheckContext(opts.target);
+  let existing = null;
+  if (opts.merge) {
+    try {
+      existing = JSON.parse(await readFile2(opts.merge, "utf8"));
+    } catch {
+      existing = null;
+    }
+  }
+  const criteria = [];
+  for (const entry of RUBRIC) {
+    const existingHit = existing?.criteria.find((c) => c.id === entry.id);
+    if (existingHit && existingHit.status === "scored") {
+      criteria.push(existingHit);
+      continue;
+    }
+    const check = allChecks[entry.id];
+    if (!check) {
+      criteria.push({
+        id: entry.id,
+        category: entry.category,
+        title: entry.title,
+        score: null,
+        status: "pending",
+        pending: "requires-agent",
+        rationale: "No deterministic check implemented; requires an agent.",
+        evidence: []
+      });
+      continue;
+    }
+    try {
+      const result = await check(ctx);
+      const criterion = {
+        id: entry.id,
+        category: entry.category,
+        title: entry.title,
+        score: result.score,
+        status: result.status ?? (result.score === null ? "pending" : "scored"),
+        evidence: result.evidence ?? [],
+        ...result.pending ? { pending: result.pending } : {},
+        ...result.rationale ? { rationale: result.rationale } : {},
+        ...result.suggestion ? { suggestion: result.suggestion } : {}
+      };
+      criteria.push(criterion);
+    } catch (err) {
+      criteria.push({
+        id: entry.id,
+        category: entry.category,
+        title: entry.title,
+        score: null,
+        status: "error",
+        rationale: `Check threw: ${err.message}`,
+        evidence: []
+      });
+    }
+  }
+  const rollup = computeRollup(criteria);
+  const backlog = generateBacklog(criteria);
+  return {
+    schemaVersion: "0.1.0",
+    rubricVersion: "0.1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    target: { path: ctx.root, name: opts.name ?? existing?.target?.name },
+    producer: {
+      kind: existing ? "merged" : "cli",
+      name: "agentready-design-cli",
+      version: "0.1.0"
+    },
+    criteria,
+    rollup,
+    backlog
+  };
+}
+
+// src/render.ts
+var CATEGORY_NAMES = {
+  1: "Tokens & Foundations",
+  2: "Component API Contract",
+  3: "Documentation Format",
+  4: "Composition & Layout",
+  5: "Retrieval & Discoverability",
+  6: "Distribution & Versioning",
+  7: "Quality Signals",
+  8: "Evaluation & Governance"
+};
+function fmt(s) {
+  if (s === null || s === void 0) return "\u2013";
+  if (Number.isInteger(s)) return String(s);
+  return s.toFixed(1);
+}
+function cell(c) {
+  if (!c) return "\u2013";
+  if (c.status === "scored" && c.score !== null) return String(c.score);
+  if (c.status === "pending") return "?";
+  if (c.status === "error") return "!";
+  if (c.status === "skipped") return "\u2014";
+  return "?";
+}
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push("# Agent-Ready Design \u2014 Assessment");
+  lines.push("");
+  lines.push(`**Target:** \`${report.target.path}\`${report.target.name ? ` _(${report.target.name})_` : ""}`);
+  lines.push(`**Producer:** ${report.producer.name ?? report.producer.kind} (${report.producer.kind})`);
+  lines.push(`**Generated:** ${report.generatedAt}`);
+  lines.push(`**Rubric version:** ${report.rubricVersion}`);
+  lines.push("");
+  const { rollup } = report;
+  lines.push("## Roll-up");
+  lines.push("");
+  lines.push(`- **Foundational floor (Categories 1\u20134): ${rollup.foundationalFloor} / 4**`);
+  lines.push(`- **Retrieval level (Category 5 max): ${rollup.retrievalLevel} / 4**`);
+  lines.push(`- **Overall median: ${fmt(rollup.overallMedian)} / 4**`);
+  lines.push(`- **Tier: ${rollup.tier} \u2014 ${TIER_LABELS[rollup.tier] ?? "?"}**`);
+  lines.push("");
+  lines.push("## Heatmap");
+  lines.push("");
+  lines.push("Legend: `0`\u2013`4` score, `?` pending agent judgment, `!` error, `\u2014` not applicable.");
+  lines.push("");
+  lines.push("| Cat | 1 | 2 | 3 | 4 | 5 | Floor | Median |");
+  lines.push("|---|---|---|---|---|---|---|---|");
+  for (const cat of [1, 2, 3, 4, 5, 6, 7, 8]) {
+    const inCat = report.criteria.filter((c) => c.category === cat);
+    const row = [1, 2, 3, 4, 5].map((i) => cell(inCat.find((c) => c.id === `${cat}.${i}`)));
+    const floor = rollup.categoryFloors[`${cat}`];
+    const med = rollup.categoryMedians[`${cat}`];
+    lines.push(
+      `| **${cat}. ${CATEGORY_NAMES[cat]}** | ${row.join(" | ")} | ${fmt(floor)} | ${fmt(med)} |`
+    );
+  }
+  lines.push("");
+  lines.push("## Per-criterion");
+  for (const cat of [1, 2, 3, 4, 5, 6, 7, 8]) {
+    lines.push("");
+    lines.push(`### Category ${cat} \u2014 ${CATEGORY_NAMES[cat]}`);
+    lines.push("");
+    for (const c of report.criteria.filter((x) => x.category === cat)) {
+      const scoreLabel = c.status === "scored" && c.score !== null ? `${c.score}/4` : c.status === "pending" ? "pending (requires agent)" : c.status === "error" ? "error" : "\u2014";
+      lines.push(`- **${c.id} ${c.title} \u2014 ${scoreLabel}**`);
+      if (c.rationale) lines.push(`  - _Rationale:_ ${c.rationale}`);
+      if (c.evidence.length > 0) {
+        const ev = c.evidence.slice(0, 4).map((e) => {
+          if (e.kind === "file") return `\`${e.path}${e.line ? ":" + e.line : ""}\`${e.detail ? " \u2014 " + e.detail : ""}`;
+          if (e.kind === "glob") return `glob \`${e.path}\`${e.detail ? " \u2014 " + e.detail : ""}`;
+          if (e.kind === "note") return e.detail ?? "(note)";
+          if (e.kind === "url") return `<${e.path}>`;
+          if (e.kind === "command") return `\`$ ${e.path}\``;
+          return e.detail ?? "";
+        }).filter(Boolean).join("; ");
+        if (ev) lines.push(`  - _Evidence:_ ${ev}`);
+      }
+      if (c.suggestion) lines.push(`  - _Suggestion:_ ${c.suggestion}`);
+    }
+  }
+  lines.push("");
+  if (report.backlog.length > 0) {
+    lines.push("## Prioritized backlog");
+    lines.push("");
+    for (const item of report.backlog) {
+      const effort = item.estimatedEffort ? ` _Effort: ${item.estimatedEffort}._` : "";
+      lines.push(
+        `${item.priority}. **${item.title}** \u2014 Criteria ${item.criteria.join(", ")}.${item.rationale ? " " + item.rationale : ""}${effort}`
+      );
+    }
+    lines.push("");
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("_Generated by [agentready-design-cli](https://github.com/hgillispie/Agent-Ready-Design). Pending rows can be completed by pasting [`prompts/self-assessment.md`](https://github.com/hgillispie/Agent-Ready-Design/blob/main/prompts/self-assessment.md) into your agent with this `agent-ready-report.json` at the repo root._");
+  return lines.join("\n");
+}
+
+export {
+  RUBRIC,
+  TOTAL_CRITERIA,
+  computeRollup,
+  TIER_LABELS,
+  generateBacklog,
+  runAssessment,
+  renderMarkdown
+};