@weatherboard/gyde-design 0.3.0

package/cli.mjs

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+/**
+ * G-53 — `gyde design`, first version.
+ *
+ * Four commands.
+ *
+ *   scan <path>   measure a repository as it is
+ *   plan <path>   say exactly what would be emitted, and write nothing
+ *   init <path>   write it; refuse to overwrite anything
+ *   gate <path>   fail on anything new since the committed ledger
+ *
+ * `plan` and `init` call the same `buildEmission()`, so the dry run cannot
+ * describe a file the real run would not write. A scaffolder whose dry run and
+ * real run can differ is one nobody can review before it writes into their
+ * repository, and sharing the call is what makes that structural rather than a
+ * promise.
+ *
+ * Everything printed carries its denominator. CHARTER §5's rule reaches the CLI
+ * too: "Gyde did not measure this" and "Gyde found nothing here" must never
+ * render the same, so skipped packages are listed by name and rules that
+ * matched nothing are reported as suspicious rather than omitted.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+
+import { discover, summarise, detectScope, detectRunner } from "./workspace.mjs";
+import { scan, format } from "./scan.mjs";
+import { SEED, generateCss, validate } from "./tokens.mjs";
+import {
+  seedBoundaries, seedDependencyBoundaries, checkBoundaries,
+  checkDependencyBoundaries, findVersionDrift,
+} from "./boundaries.mjs";
+import { emitTokens, emitSystem, emitConfig, SEED_COMPONENTS, SCAFFOLD_VERSION, NOT_UPGRADEABLE } from "./emit.mjs";
+import { emitCatalogue } from "./catalogue.mjs";
+import { emitAgentDocs } from "./agentdocs.mjs";
+import { emitWorkflow } from "./workflow.mjs";
+import { buildManifest, readManifest, writeManifest, applyUpgrade, formatUpgrade, MANIFEST } from "./upgrade.mjs";
+import { exportedComponents, renderableComponents, checkWiring, formatWiring, WIRING } from "./wiring.mjs";
+import { checkClientBoundary, formatClientBoundary, blocks as clientBoundaryBlocks } from "./clientboundary.mjs";
+import { checkDocDrift, formatDocDrift } from "./docdrift.mjs";
+import { reconcile } from "./adoption.mjs";
+import { detectTailwind, formatTailwind } from "./tailwind.mjs";
+import { migrationProgress, formatMigration } from "./migration.mjs";
+import { checkStyleX, formatStyleX } from "./stylex.mjs";
+import { blocksAt, formatSchedule, SCHEDULE } from "./enforcement.mjs";
+import { buildUsage, guidance, formatUsage } from "./usage.mjs";
+import { record, gate, formatGate, adopt, LEDGER_NOTE } from "./ratchet.mjs";
+import { loadRules } from "./rules.mjs";
+
+/**
+ * The single source of what would be written.
+ *
+ * `plan` prints these paths and `init` writes these contents — the same call, so
+ * the dry run cannot describe something the real run does not do. Any future
+ * emitter belongs here and nowhere else.
+ */
+/**
+ * The repository's default branch, read from git rather than assumed.
+ *
+ * `main` is the common case and not the universal one — the first repository
+ * this was installed into uses `staging`, where a hardcoded `branches: [main]`
+ * silently never fires. Returns null when it cannot tell, so the caller falls
+ * back explicitly instead of this function inventing an answer.
+ */
+function detectDefaultBranch(root) {
+  try {
+    const head = execFileSync("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+      { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return head.replace(/^origin\//, "") || null;
+  } catch { /* no remote, or a repo with no origin/HEAD set */ }
+  try {
+    return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"],
+      { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+  } catch { return null; }
+}
+
+function buildEmission(design, { hasTokens, hasSystem, scope, rootDir }) {
+  const systemPath = design.systemPath || "packages/design-system";
+  const tokensPath = design.tokensPath || "packages/design-tokens";
+  const primitive = design.primitive || "@base-ui/react";
+
+  /**
+   * The names the emitted code imports.
+   *
+   * Derived from the workspace's own scope, never invented. A hardcoded
+   * placeholder made every emitted import resolve to nothing — a scaffolded
+   * repository that would not build, with every test green because each
+   * compared the emitted text against itself.
+   *
+   * A workspace with no scope at all has to say what it wants: guessing a name
+   * is how you get a package nobody can import and nobody can find.
+   */
+  const ns = design.scope || scope;
+  if (!ns) {
+    throw new Error(
+      "Could not determine an npm scope for this workspace, and will not invent one.\n" +
+      "Set `design.scope` in gyde.config.json (e.g. \"@acme\") — emitted code has to\n" +
+      "import the packages it emits, and a guessed name resolves to nothing.");
+  }
+  const systemPackage = design.systemPackage || `${ns}/design-system`;
+  const tokensPackage = design.tokensPackage || `${ns}/design-tokens`;
+  const cataloguePackage = design.cataloguePackage || `${ns}/design-catalogue`;
+
+  let files = {};
+  // An existing package is audited, never regenerated over. Emitting into a
+  // directory somebody already owns is the one thing a scaffolder must not do
+  // by default (G-47).
+  if (!hasTokens) files = { ...files, ...emitTokens(undefined, { path: tokensPath, tokensPackage }) };
+  if (!hasSystem) {
+    files = { ...files, ...emitSystem({ primitive, path: systemPath, tokensPackage, systemPackage }) };
+    // The catalogue is emitted with the set, never separately: it is generated
+    // from the same component list the barrel is, which is what makes coverage
+    // true by construction rather than by a test somebody has to keep passing.
+    files = { ...files, ...emitCatalogue({ components: SEED_COMPONENTS, path: design.cataloguePath || "apps/design", systemPackage, tokensPackage, cataloguePackage }) };
+  }
+
+  /**
+   * The agent doc, decided by what is ON DISK — never by the caller's flags.
+   *
+   * Outside the `hasSystem` branch on purpose, and G-66 is why. `upgrade`
+   * passes `hasSystem: false` deliberately, so a scaffolded repository still
+   * receives component template fixes. Any doc decision taken inside that
+   * branch therefore reads "greenfield" in EVERY repository, including ones
+   * with fifty-six components of their own.
+   *
+   * That is not hypothetical — it shipped, an hour after the same bug was
+   * fixed one level up. System B received a document containing
+   * `### Button` and a prop table, for a Button Gyde has never seen. The flag
+   * said greenfield; the repository was not. A fix that trusts the same wrong
+   * input as the bug is not a fix.
+   *
+   * So the question is put to the filesystem instead. A parseable barrel with
+   * real components means the product owns the set and Gyde documents names
+   * only. No barrel means Gyde is about to emit the seed set, and can describe
+   * it fully because it wrote it.
+   *
+   * This is the one emitted artefact that changes what gets WRITTEN rather
+   * than judging what was: an agent that knows the set uses it, and one that
+   * does not gets audited for not using it — the expensive order.
+   */
+  const theirs = renderableComponents(rootDir, systemPath);
+  files = { ...files, ...emitAgentDocs(theirs
+    ? { components: theirs, systemPackage, verified: false }
+    : { components: SEED_COMPONENTS, systemPackage, verified: true }) };
+
+  /**
+   * The gate.
+   *
+   * Emitted even when a design system already exists, because the workflow is
+   * what makes the verdict binding and an adopting repository needs it most.
+   * Without it `gate` is a command somebody remembers to type, which is the
+   * most complete skip there is.
+   */
+  // Detected ONCE, here, then handed to both the workflow and the config it is
+  // recorded in. Re-detecting on a later run is how a workflow silently
+  // changes under a repository (G-66).
+  const runsOn = design.runsOn || detectRunner(rootDir) || "ubuntu-latest";
+  const defaultBranch = design.defaultBranch || detectDefaultBranch(rootDir) || "main";
+
+  files = { ...files, ...emitWorkflow({
+    action: design.action || undefined,
+    failOn: design.failOn || undefined,
+    runsOn,
+    defaultBranch,
+  }) };
+  files = { ...files, ...emitConfig({ systemPath, tokensPath, primitive, scope: ns, foreignPaths: design.foreignPaths || [], defaultBranch, runsOn }) };
+  return files;
+}
+
+const PRIMITIVES = [
+  { name: "@base-ui/react", label: "Base UI" },
+  { name: "@base-ui-components/react", label: "Base UI (pre-1.0 package name)" },
+  { name: "@radix-ui/react-dialog", label: "Radix", family: /^@radix-ui\// },
+];
+
+/** Read gyde.config.json if the project has one. Absent is fine; guessed is not. */
+function readConfig(root) {
+  const path = join(root, "gyde.config.json");
+  if (!existsSync(path)) return { present: false, design: {} };
+  try {
+    const json = JSON.parse(readFileSync(path, "utf8"));
+    return { present: true, design: json.design || {} };
+  } catch (e) {
+    throw new Error(`gyde.config.json exists but could not be parsed: ${e.message}\n` +
+      "Refusing to continue on a default — a misread config is how a project ends up measured against a scope nobody chose.");
+  }
+}
+
+/** What the repository already uses, read from manifests rather than assumed. */
+function detectStack(root, packages) {
+  const found = { primitives: [], styling: [], tokens: null };
+  for (const pkg of packages) {
+    const manifest = join(root, pkg.path === "." ? "" : pkg.path, "package.json");
+    if (!existsSync(manifest)) continue;
+    let json; try { json = JSON.parse(readFileSync(manifest, "utf8")); } catch { continue; }
+    const deps = { ...(json.dependencies || {}), ...(json.devDependencies || {}) };
+    for (const name of Object.keys(deps)) {
+      for (const p of PRIMITIVES) {
+        if (name === p.name || (p.family && p.family.test(name))) {
+          const label = `${p.label} (${name}@${deps[name]})`;
+          if (!found.primitives.some((x) => x.startsWith(p.label))) found.primitives.push(`${p.label} — first seen ${pkg.path}`);
+        }
+      }
+      if (/^tailwindcss$/.test(name)) found.styling.push(`Tailwind ${deps[name]} in ${pkg.path}`);
+      if (/^@stylexjs\/stylex$/.test(name)) found.styling.push(`StyleX ${deps[name]} in ${pkg.path}`);
+    }
+  }
+  found.primitives = [...new Set(found.primitives)];
+  found.styling = [...new Set(found.styling)];
+  return found;
+}
+
+function cmdScan(root, config) {
+  const ws = discover(root);
+  const sum = summarise(ws);
+
+  console.log(`workspace    ${sum.source}`);
+  console.log(`             ${sum.carryUI.length} package(s) render UI: ${sum.carryUI.join(", ") || "none"}`);
+  if (sum.skipped.length) {
+    console.log(`skipped      ${sum.skipped.length}, each with a reason:`);
+    for (const s of sum.skipped) console.log(`               ${s.path} — ${s.because}`);
+  }
+  if (sum.uiWithoutPipeline.length) {
+    console.log(`no pipeline  ${sum.uiWithoutPipeline.join(", ")}`);
+  }
+
+  const stack = detectStack(root, ws.packages);
+  console.log(`primitives   ${stack.primitives.join("; ") || "none detected"}`);
+  console.log(`styling      ${stack.styling.join("; ") || "none detected"}`);
+  console.log("");
+
+  // The barrel is read once and handed to the scan, so markup adoption (G-73)
+  // and the compound check (G-72) are measured against the same export list the
+  // rest of this command reports on. Re-deriving it per call site is how the
+  // three `scan` invocations in this file drifted the first time.
+  const scanRoots = exportedComponents(root, config.design?.systemPath || "packages/design-system");
+  const result = scan(root, {
+    config: { ...config.design, componentRoots: scanRoots ? new Set(scanRoots) : null },
+  });
+  console.log(format(result));
+
+  const drift = findVersionDrift(root, { packages: ws.packages, match: /^(@radix-ui|@base-ui)/ });
+  if (drift.length) {
+    console.log(`\ndrift        ${drift.length} primitive package(s) pinned at more than one version:`);
+    for (const d of drift.slice(0, 8)) {
+      console.log(`               ${d.dependency}  ${Object.entries(d.versions).map(([p, v]) => `${p}=${v}`).join("  ")}`);
+    }
+    if (drift.length > 8) console.log(`               … and ${drift.length - 8} more`);
+  }
+
+  const design = config.design || {};
+  const systemPath = design.systemPath || "packages/design-system";
+  const components = exportedComponents(root, systemPath);
+
+  if (components || ws.packages.some((p) => p.path === systemPath)) {
+    console.log("");
+    console.log(formatWiring(checkWiring(root, ws.packages, {
+      systemPath,
+      systemPackage: design.systemPackage || null,
+      tokensPackage: design.tokensPackage || null,
+    })));
+  }
+
+  // G-67. Reported wherever the system is measured, because the defect it
+  // finds is invisible at every other gate: the source reads as correct and
+  // the build passes.
+  console.log("");
+  console.log(formatClientBoundary(checkClientBoundary(root, { packages: ws.packages })));
+
+  // G-70. contract.md ranks docs-rot the highest-priority intake class, because
+  // a doc naming a deleted component still looks authoritative and an agent
+  // reads it first.
+  // G-98. Printed with the class count beside it, because the dependency must
+  // not be removed while classes still resolve through it.
+  // G-100. The positive half of G-98: one styling layer, and it is wired.
+  console.log("");
+  console.log(formatStyleX(checkStyleX(root, { packages: ws.packages, renders: sum.carryUI })));
+
+  console.log("");
+  console.log(formatTailwind(detectTailwind(root, {
+    packages: ws.packages,
+    utilityClasses: result.tailwindClasses,
+    cssDirectives: result.tailwindCssDirectives,
+  })));
+
+  console.log("");
+  console.log(formatDocDrift(checkDocDrift(root, {
+    systemPackage: design.systemPackage || null,
+    exports: components,
+    // G-96. Which documents the product declares are component contracts.
+    // Undeclared, the prose assertion does not run and the report says so.
+    contractDocs: design.contractDocs || [],
+  })));
+
+  if (components) {
+    const usage = buildUsage(root, {
+      components,
+      excludePaths: [systemPath, ...(design.usageExcludePaths || [])],
+      classPrefixes: design.classPrefixes || ["ds-"],
+    });
+    const found = guidance(usage);
+    console.log("");
+    console.log(formatUsage(usage, found));
+  }
+
+  if (!config.present) {
+    console.log(
+      "\nnote         no gyde.config.json — every path was treated as product code.\n" +
+      "             `systemPaths` and `foreignPaths` suppress findings, so they are\n" +
+      "             configuration a project commits, never something Gyde infers.",
+    );
+  }
+  return result.findings.length === 0 ? 0 : 0; // scan reports; the gate decides (G-52)
+}
+
+function cmdPlan(root, config) {
+  const ws = discover(root);
+  const sum = summarise(ws);
+  const stack = detectStack(root, ws.packages);
+  const design = config.design || {};
+  const systemPath = design.systemPath || "packages/design-system";
+  const tokensPath = design.tokensPath || "packages/design-tokens";
+
+  const alreadyHasSystem = ws.packages.some((p) => p.path === systemPath);
+  const alreadyHasTokens = ws.packages.some((p) => p.path === tokensPath);
+
+  /**
+   * An existing component library does not have to be at the path Gyde would
+   * have chosen.
+   *
+   * The first version checked only `packages/design-system` and declared
+   * System C GREENFIELD — a repository with 22 shadcn components, a
+   * token dictionary and two apps consuming it in 109 files. Scaffolding on top
+   * of that would have been the most destructive thing this tool could do, and
+   * it would have been done confidently. So look for the shape, not the name:
+   * a UI-bearing package that is not an application.
+   */
+  const candidateLibraries = ws.packages.filter((p) =>
+    p.carriesUI && p.pipelines.every((x) => x.kind !== "next" && x.kind !== "expo") &&
+    p.path !== systemPath && p.path !== tokensPath);
+
+  const mode = alreadyHasSystem || alreadyHasTokens || candidateLibraries.length ? "adoption" : "greenfield";
+
+  console.log(`mode         ${mode}`);
+  if (mode === "adoption") {
+    console.log("             a component library already exists here. Gyde records current debt");
+    console.log("             as allowances and ratchets from there. Amnesty never (CHARTER §4).");
+    for (const c of candidateLibraries) {
+      console.log(`             found: ${c.path}${c.name ? ` (${c.name})` : ""} — not at Gyde's default path,`);
+      console.log("                    so adopting it in place is a decision, not a default (G-61).");
+    }
+  } else {
+    console.log("             no UI-bearing library package found; the baseline starts and stays at zero.");
+  }
+  console.log("");
+
+  // The SAME call init makes. plan cannot describe a file init would not write.
+  const files = buildEmission(design, { hasTokens: alreadyHasTokens, hasSystem: alreadyHasSystem, scope: detectScope(ws).scope, rootDir: root });
+  console.log(`would emit   ${Object.keys(files).length} file(s)`);
+  for (const path of Object.keys(files).sort()) {
+    const exists = existsSync(join(root, path));
+    console.log(`  ${exists ? "SKIP" : "    "} ${path}${exists ? "   already exists — init refuses to overwrite" : ""}`);
+  }
+  if (alreadyHasTokens) console.log(`  ${tokensPath}/ EXISTS — audited, never regenerated over`);
+  if (alreadyHasSystem) console.log(`  ${systemPath}/ EXISTS — closure enforced on it, not replaced`);
+
+  console.log("\nwould wire");
+  const pipelines = sum.pipelines;
+  if (pipelines.length === 0) console.log("  nothing — no build pipeline was found in any UI package");
+  for (const p of pipelines) console.log(`  ${p}`);
+  if (sum.uiWithoutPipeline.length) {
+    console.log(`  NOT WIRED, and reported rather than skipped: ${sum.uiWithoutPipeline.join(", ")}`);
+  }
+
+  console.log("\nwould leave alone");
+  for (const s of sum.skipped) console.log(`  ${s.path.padEnd(42)} ${s.because}`);
+
+  console.log("\nprimitive layer");
+  if (stack.primitives.length === 0) {
+    console.log("  none present — Gyde would install one (G-58 decides which)");
+  } else {
+    console.log(`  ${stack.primitives.join("\n  ")}`);
+    console.log("  present already. Whether Gyde adopts this in place or migrates it is G-61,");
+    console.log("  and it is an open question rather than something this command should assume.");
+  }
+
+  const boundaries = seedBoundaries({
+    primitive: design.primitive || "@base-ui/react",
+    systemPath, tokensPath,
+    appPaths: sum.carryUI.filter((p) => p !== systemPath && p !== tokensPath),
+  });
+  const { breaches } = checkBoundaries(root, boundaries);
+  const depBreaches = checkDependencyBoundaries(root, seedDependencyBoundaries({
+    primitive: design.primitive || "@base-ui/react", systemPath,
+  }), { packages: ws.packages });
+
+  console.log("\nboundaries it would enforce");
+  for (const b of boundaries) {
+    for (const f of b.forbid) {
+      console.log(`  ${(b.from || "(everywhere)").padEnd(28)} may not import ${f.pattern.source}`);
+    }
+  }
+  console.log(`  → ${breaches.length} import breach(es), ${depBreaches.length} dependency breach(es) today`);
+  for (const b of breaches.slice(0, 5)) console.log(`     ${b.file}:${b.line}  ${b.source}`);
+  for (const b of depBreaches.slice(0, 5)) console.log(`     ${b.package} declares ${b.dependency}@${b.version}`);
+
+  const roots = exportedComponents(root, design.systemPath || "packages/design-system");
+  const result = scan(root, { config: { ...design, componentRoots: roots ? new Set(roots) : null } });
+  console.log(`\nbaseline it would record`);
+  console.log(`  ${result.findings.length} finding(s) across ${result.scope.filesWithStyling} file(s) with styling`);
+  console.log(`  adoption ${result.adoption.percent ?? "n/a"}% (${result.adoption.tokenised} of ${result.adoption.of} declarations)`);
+  console.log("  This is a debt with a direction: the list may only ever get shorter.");
+
+  console.log("\nnothing was written. `gyde design init` executes exactly this emission.");
+  return 0;
+}
+
+/**
+ * Write the plan.
+ *
+ * Refuses to overwrite anything. Gyde emits once and the file becomes the
+ * product's (G-47); a scaffolder that clobbers an existing file has taken
+ * ownership of something it does not own, and it would do it silently.
+ */
+function cmdInit(root, config) {
+  const ws = discover(root);
+  const design = config.design || {};
+  const systemPath = design.systemPath || "packages/design-system";
+  const tokensPath = design.tokensPath || "packages/design-tokens";
+
+  const files = buildEmission(design, {
+    hasTokens: ws.packages.some((p) => p.path === tokensPath),
+    hasSystem: ws.packages.some((p) => p.path === systemPath),
+    scope: detectScope(ws).scope,
+    rootDir: root,
+  });
+
+  const written = [];
+  const refused = [];
+  for (const [rel, contents] of Object.entries(files)) {
+    const full = join(root, rel);
+    if (existsSync(full)) { refused.push(rel); continue; }
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, contents);
+    written.push(rel);
+  }
+
+  // Provenance for everything actually written. Without it an upgrade cannot
+  // tell the product's edit from Gyde's change, and has to choose between
+  // clobbering and doing nothing — which is shadcn's unsolved problem (G-61).
+  if (written.length) {
+    const emitted = Object.fromEntries(
+      written.filter((w) => !NOT_UPGRADEABLE.has(w)).map((w) => [w, files[w]]));
+    const existing = readManifest(root);
+    const manifest = buildManifest(emitted, { version: SCAFFOLD_VERSION });
+    if (existing) manifest.files = { ...existing.files, ...manifest.files };
+    writeManifest(root, manifest);
+  }
+
+  for (const w of written.sort()) console.log(`wrote   ${w}`);
+  for (const r of refused.sort()) console.log(`refused ${r}   already exists; Gyde never overwrites`);
+  if (written.length) console.log(`wrote   ${MANIFEST}   (provenance: what was emitted, so an upgrade can tell your edits from ours)`);
+
+  console.log(`\n${written.length} written, ${refused.length} refused.`);
+  if (written.length) {
+    console.log("\nEvery emitted file is yours now. Replace the placeholder values —");
+    console.log("that is the point. What stays checked is the shape: closure, the token");
+    console.log("contract, and the boundary rules.");
+  }
+  // A half-finished scaffold must not look like a finished one.
+  return refused.length && !written.length ? 1 : 0;
+}
+
+/**
+ * Take a new template version into an already-scaffolded repository.
+ *
+ * The whole mechanism is in upgrade.mjs; this is the surface. `--dry-run`
+ * shares the same call, for the same reason `plan` and `init` do.
+ */
+function cmdUpgrade(root, config, { dryRun }) {
+  const ws = discover(root);
+  const design = config.design || {};
+  const systemPath = design.systemPath || "packages/design-system";
+  const tokensPath = design.tokensPath || "packages/design-tokens";
+
+  const manifest = readManifest(root);
+  if (!manifest) {
+    console.log(`no ${MANIFEST} — this repository was not scaffolded by a version of Gyde that`);
+    console.log("records provenance. Every emitted path is therefore UNTRACKED, and untracked");
+    console.log("means untouched: an upgrade would be a guess about which side owns each file.");
+    console.log("\nRun `init` in a scratch copy and diff, or adopt the current files by hand.");
+    return 1;
+  }
+
+  // What THIS version would emit for a fresh repo, regardless of what exists —
+  // an upgrade compares against the templates, not against a skip decision.
+  // The same call init makes, so a fresh scaffold reports no drift.
+  const next = buildEmission(design, { hasTokens: false, hasSystem: false, scope: detectScope(ws).scope, rootDir: root });
+  delete next["gyde.config.json"];
+
+  const result = applyUpgrade(root, next, manifest, { version: SCAFFOLD_VERSION, dryRun });
+  console.log(formatUpgrade(result, { manifest, version: SCAFFOLD_VERSION }));
+
+  if (!dryRun) {
+    writeManifest(root, result.nextManifest);
+    console.log(`\nprovenance updated. An unapplied change keeps its old baseline, so a`);
+    console.log("conflict is offered again next time rather than quietly becoming yours.");
+  } else {
+    console.log("\nnothing was written.");
+  }
+
+  // Conflicts are not a failure of the upgrade — they are its output. But they
+  // need somebody, so they exit non-zero rather than scrolling past in CI.
+  return result.conflicts.length ? 1 : 0;
+}
+
+/**
+ * The gate.
+ *
+ * Reads the committed ledger, rescans, and fails on anything new. With no
+ * ledger it records one and says so — recording debt is the sanctioned entry
+ * path (CHARTER §4, amnesty never), and it is never a silent pass.
+ */
+/**
+ * Evidence that the gate actually ran.
+ *
+ * An exit code is not evidence: a step that was skipped, filtered out by a
+ * `paths:` rule, or never reached leaves a green job behind and no way to tell
+ * it from a clean pass. That is the failure `verify-tier` documents six times
+ * over, and CHARTER §5 exists because of it.
+ *
+ * WRITTEN ON EVERY EXIT PATH, INCLUDING THE FAILURES. The first version wrote
+ * it only after a verdict, so the baseline-recording run — which exits non-zero
+ * on purpose — produced none, and the workflow's proof step then reported "the
+ * gate did not run" for a gate that had just run and recorded a baseline.
+ *
+ * That is the same confusion this product is built to prevent, in its own
+ * code: a check that cannot distinguish ABSENT from DID SOMETHING ELSE will
+ * report the wrong one, confidently. So the evidence carries `why`, and every
+ * path writes it.
+ */
+function writeEvidence(root, result, { ok, why, clientBoundary = null, enforcement = null }) {
+  mkdirSync(join(root, ".gyde"), { recursive: true });
+  writeFileSync(join(root, ".gyde", "last-verdict.json"), JSON.stringify({
+    "//": "Written by `gyde-design gate`. Proof the gate ran, not just that a job went green.",
+    ranAt: process.env.GYDE_RUN_ID || null,
+    ok,
+    why,
+    findings: result ? result.findings.length : null,
+    filesWithStyling: result ? result.scope.filesWithStyling : null,
+    filesWalked: result ? result.scope.filesWalked : null,
+    /**
+     * G-74. The RECONCILED figure, not the token layer.
+     *
+     * action.yml reads `adoption.percent` for the job summary. Leaving the
+     * token number here while the CLI printed the weakest layer would have put
+     * 75% on a pull request and 20% in a terminal, for the same commit — which
+     * is the two-teams-disagree failure this issue exists to end, reintroduced
+     * by the fix for it.
+     *
+     * `percent` may be null when a layer could not be measured. The action
+     * already renders an empty adoption as `n/a`, which is the correct reading:
+     * not measured is not zero.
+     */
+    adoption: result ? reconcile({
+      token: { ...result.adoption, used: result.adoption.tokenised },
+      markup: result.markup?.unknown ? null : result.markup?.adoption,
+    }) : null,
+    rulesThatMatchedNothing: result ? result.coverage.filter((c) => !c.matched).map((c) => c.rule) : [],
+    clientBoundary,
+    enforcement,
+  }, null, 2) + "\n");
+}
+
+function cmdGate(root, config) {
+  const design = config.design || {};
+  const ledgerPath = join(root, "gyde-allowance.json");
+  const roots = exportedComponents(root, design.systemPath || "packages/design-system");
+  const result = scan(root, { config: { ...design, componentRoots: roots ? new Set(roots) : null } });
+
+  if (!existsSync(ledgerPath)) {
+    const led = record(result.findings, {
+      recorded: process.env.GYDE_DATE || null,
+      rules: result.rulesRun,
+    });
+    writeFileSync(ledgerPath, JSON.stringify(led, null, 2) + "\n");
+    console.log(`no ledger found — recorded ${led.total} existing finding(s) as the baseline.`);
+    console.log(`wrote gyde-allowance.json\n`);
+    console.log(LEDGER_NOTE);
+    console.log("\nThis run recorded a baseline rather than judging one. It is not a pass.");
+    writeEvidence(root, result, { ok: false, why: "recorded a baseline; nothing was judged" });
+    return 1;
+  }
+
+  let ledger;
+  try { ledger = JSON.parse(readFileSync(ledgerPath, "utf8")); }
+  catch (e) {
+    console.error(`gyde-allowance.json could not be parsed: ${e.message}`);
+    writeEvidence(root, result, { ok: false, why: `the ledger could not be parsed: ${e.message}` });
+    return 1;
+  }
+
+  const verdict = gate([{ name: "design-system", findings: result.findings, ledger }]);
+  console.log(formatGate(verdict));
+
+  // G-99. No gate and no verdict change — the ratchet was already correct for a
+  // migration. This subtracts two numbers the ledger has carried since G-52, so
+  // that "not started" and "not visible from here" stop reading the same.
+  const migrating = design.migrating || [];
+  if (migrating.length) {
+    console.log("");
+    console.log(formatMigration(migrationProgress(result.findings, ledger, { migrating })));
+  }
+
+  // G-68. Written, not just reported. An adoption that stays in stdout is
+  // adopted again on the next run, so the rule reports forever and ratchets
+  // never — which is the to-do-list-nobody-reads failure LEDGER_NOTE names.
+  if (verdict.adopted.length) {
+    writeFileSync(ledgerPath, JSON.stringify(
+      adopt(ledger, verdict.adopted, { rules: result.rulesRun }), null, 2) + "\n");
+  }
+
+  // G-67. Deliberately NOT a ledger finding. A crossing is a runtime defect
+  // rather than style debt, so allowancing one would record "this renders
+  // undefined props, and that is fine for now" as a committed number. It is
+  // gated on the product's own template version instead — see BLOCKS_FROM.
+  // Discovered once and shared by every check below. Calling `discover` per
+  // check re-walks the workspace and, more importantly, lets two checks in the
+  // same run disagree about which packages exist.
+  const ws = discover(root);
+  const cb = checkClientBoundary(root, { packages: ws.packages });
+  const cbBlocks = clientBoundaryBlocks(readManifest(root)?.version);
+  if (cb.crossings.length || cb.unresolved.length) {
+    console.log("");
+    console.log(formatClientBoundary(cb, { blocking: cb.crossings.length ? cbBlocks : null }));
+  }
+
+  /**
+   * G-101. The mandates, enforced on the same schedule as the client boundary.
+   *
+   * Each is reported wherever it is measured and blocks only from the template
+   * version in the SCHEDULE, which the product takes by running `upgrade`. The
+   * schedule is printed whenever anything on it is advisory, so a consumer can
+   * see what taking the next version costs before they take it — the question
+   * a changelog answers badly and a generated table answers exactly.
+   */
+  const templateVersion = readManifest(root)?.version ?? null;
+
+  const tw = detectTailwind(root, {
+    packages: ws.packages,
+    utilityClasses: result.tailwindClasses,
+    cssDirectives: result.tailwindCssDirectives,
+  });
+  const sx = checkStyleX(root, { packages: ws.packages, renders: summarise(ws).carryUI });
+
+  const breaches = [
+    { rule: "client-boundary", n: cb.crossings.length, what: `${cb.crossings.length} value(s) crossing the "use client" boundary` },
+    { rule: "tailwind-present", n: tw.present ? tw.dependencies.length + tw.configs.length : 0, what: "Tailwind is installed" },
+    { rule: "tailwind-in-css", n: result.tailwindCssDirectives, what: `${result.tailwindCssDirectives} Tailwind directive(s) in stylesheets` },
+    { rule: "styling-layer", n: sx.unknown ? 0 : sx.missing.length + sx.unwired.length + sx.competing.length, what: "the styling layer is not StyleX, or is not wired" },
+  ].filter((b) => b.n > 0);
+
+  const blocking = breaches.filter((b) => blocksAt(b.rule, templateVersion));
+
+  if (breaches.length) {
+    console.log("");
+    console.log(formatSchedule(templateVersion));
+  }
+
+  const ok = verdict.ok && blocking.length === 0;
+  const why = !verdict.ok ? "new findings since the ledger"
+    : blocking.length ? blocking.map((b) => b.what).join("; ")
+    : "held";
+
+  writeEvidence(root, result, {
+    ok, why,
+    clientBoundary: { crossings: cb.crossings.length, unresolved: cb.unresolved.length, blocking: cbBlocks },
+    enforcement: {
+      templateVersion,
+      blocking: blocking.map((b) => b.rule),
+      advisory: breaches.filter((b) => !blocksAt(b.rule, templateVersion)).map((b) => b.rule),
+    },
+  });
+
+  return ok ? 0 : 1;
+}
+
+function main(argv) {
+  const [cmd, pathArg] = argv;
+  if (!cmd || ["-h", "--help", "help"].includes(cmd)) {
+    console.log("gyde design <scan|plan|init|gate|tokens> [path]");
+    console.log("  scan    measure a repository as it is");
+    console.log("  plan    say what scaffolding would be emitted; write nothing");
+    console.log("  init    write exactly what plan described; never overwrites");
+    console.log("  gate    fail on anything new since the committed ledger");
+    console.log("  upgrade take a new template version; never merges a conflict");
+    console.log("          (--dry-run to see the decisions and write nothing)");
+    console.log("  tokens  print the generated stylesheet for the seed dictionary");
+    return 0;
+  }
+  if (cmd === "tokens") {
+    const problems = validate(SEED);
+    if (problems.length) { console.error(problems.join("\n")); return 1; }
+    console.log(generateCss(SEED));
+    return 0;
+  }
+
+  const root = resolve(pathArg || ".");
+  if (!existsSync(root)) { console.error(`no such path: ${root}`); return 1; }
+  const config = readConfig(root);
+
+  if (cmd === "scan") return cmdScan(root, config);
+  if (cmd === "plan") return cmdPlan(root, config);
+  if (cmd === "init") return cmdInit(root, config);
+  if (cmd === "gate") return cmdGate(root, config);
+  if (cmd === "upgrade") return cmdUpgrade(root, config, { dryRun: argv.includes("--dry-run") });
+  console.error(`unknown command: ${cmd}`);
+  return 1;
+}
+
+process.exitCode = main(process.argv.slice(2));