@weatherboard/gyde-design 0.4.0 → 0.4.1

package/ratchet.mjs

@@ -116,7 +116,13 @@ export function rulesKnownTo(ledger) {
 }
 
 /**
- * Fold adopted entries into a ledger, and record which rules it now knows.
+ * Fold new-rule entries into a ledger, and record which rules it now knows.
+ *
+ * G-108: this is now reached ONLY from `gate --record-new-rules`. It used to run
+ * automatically whenever `compare` adopted, which meant merely running the gate
+ * on a laptop could make a consumer's ledger 80 entries longer — a ledger
+ * getting longer by a mechanism nobody chose. `gate` no longer writes the ledger
+ * at all unless asked in those words.
  *
  * Separate from `record` because it is not the same act. `record` takes a
  * measurement of everything; this takes an existing measurement and adds the
@@ -146,6 +152,127 @@ export function adopt(ledger, adopted, { rules }) {
   };
 }
 
+/**
+ * G-113 — take a shortening, and nothing else.
+ *
+ * THE GAP THIS CLOSES. Every other writer does strictly more than remove.
+ * `record` re-baselines everything currently found; `adopt` only adds. So the
+ * one operation the standing rule always wants — *make the ledger shorter* —
+ * had no command, and the only mechanically available route was "delete the
+ * ledger and re-run `gate`". That route is provably identical to a correct trim
+ * **only when `failures` is 0**, which is a precondition invisible to anybody
+ * reading the diff six months later. Ten scoped issues each end in a shortening;
+ * doing it that way ten times is ten chances to perform the exact operation the
+ * mechanism exists to prevent.
+ *
+ * WHY IT REFUSES RATHER THAN CLAMPS. The obvious implementation takes
+ * `min(budget, count)` per entry and can therefore never grow the ledger. It is
+ * also wrong, and wrong in the direction that looks like success: pointed at a
+ * tree with a real regression it silently writes a *shorter* ledger while the
+ * regression goes unreported, converting a red gate into a green one and calling
+ * it progress. A trim that can absorb anything is `record` with a friendlier
+ * name. So a would-add and a would-raise are both hard refusals, the whole
+ * write is abandoned, and the caller is told which entries objected.
+ *
+ * WHAT IT PRESERVES. `ticket`, `recorded` and `rules` are carried through
+ * untouched. `rules` especially: dropping it re-opens G-108 exactly, because a
+ * ledger that does not name its rules is treated as knowing only LEGACY_RULES,
+ * and every rule shipped since would be re-adopted as pre-existing debt on the
+ * next run. A trim that loses `rules` is a trim that quietly widens the
+ * allowance it was meant to narrow.
+ *
+ * Returns `{ ok, ledger, removed, lowered, unchanged, refusals, before, after }`.
+ * `ledger` is null when `ok` is false — there is no partial trim to write.
+ */
+export function trim(ledger, findings) {
+  const current = tally(findings);
+  const allowed = ledger?.allowed ?? {};
+
+  const removed = [];
+  const lowered = [];
+  const refusals = [];
+  let unchanged = 0;
+
+  const next = {};
+  for (const [file, rules] of Object.entries(allowed)) {
+    for (const [rule, budget] of Object.entries(rules)) {
+      const count = current[file]?.[rule] ?? 0;
+      if (count > budget) {
+        // A genuine regression. Not ours to absorb, and not ours to hide.
+        refusals.push({
+          file, rule, count, allowed: budget, kind: "increased",
+          why: `was ${budget}, now ${count}. A trim only ever removes; this is a regression for \`gate\` to fail on.`,
+        });
+        continue;
+      }
+      if (count === 0) { removed.push({ file, rule, allowed: budget }); continue; }
+      if (count < budget) {
+        lowered.push({ file, rule, count, allowed: budget });
+        (next[file] ??= {})[rule] = count;
+        continue;
+      }
+      unchanged++;
+      (next[file] ??= {})[rule] = budget;
+    }
+  }
+
+  // Anything the scan found that the ledger does not carry would have to be
+  // ADDED, and adding is the one thing this command must never do — whether the
+  // entry is new, was cleared and re-added, or belongs to a rule this ledger has
+  // never named. `gate` distinguishes those three because the conversations
+  // differ; here the answer is the same for all of them, so they share a path.
+  for (const [file, rules] of Object.entries(current)) {
+    for (const [rule, count] of Object.entries(rules)) {
+      if (allowed[file]?.[rule] === undefined) {
+        refusals.push({
+          file, rule, count, allowed: 0, kind: "new",
+          why: "not in the ledger — a trim would have to ADD it. Run `gate` to judge this properly.",
+        });
+      }
+    }
+  }
+
+  const before = Object.values(allowed).reduce(
+    (n, rs) => n + Object.values(rs).reduce((m, c) => m + c, 0), 0);
+
+  if (refusals.length) {
+    return { ok: false, ledger: null, removed: [], lowered: [], unchanged, refusals, before, after: before };
+  }
+
+  const total = Object.values(next).reduce(
+    (n, rs) => n + Object.values(rs).reduce((m, c) => m + c, 0), 0);
+
+  return {
+    ok: true,
+    // Spread first so `recorded`, `ticket` and anything a future field adds
+    // survives; the named keys below are the only ones a trim may change.
+    ledger: { ...ledger, note: LEDGER_NOTE, total, allowed: sortDeep(next) },
+    removed, lowered, unchanged, refusals: [], before, after: total,
+  };
+}
+
+/** A per-entry account of a trim. The audit trail IS the point of this file. */
+export function formatTrim(result) {
+  const L = [];
+  if (!result.ok) {
+    L.push(`✖ refused to trim: ${result.refusals.length} entry(ies) would have to be added or raised.`);
+    L.push("");
+    for (const r of result.refusals.slice(0, 20)) L.push(`    ${r.file}  ${r.rule}  ${r.why}`);
+    if (result.refusals.length > 20) L.push(`    … and ${result.refusals.length - 20} more`);
+    L.push("");
+    L.push("A trim only ever removes. Nothing was written — the ledger on disk is unchanged.");
+    L.push("This tree has findings the ledger does not cover; that is a gate failure, not a trim.");
+    return L.join("\n");
+  }
+  for (const r of result.removed) L.push(`  - ${r.file}  ${r.rule}  ${r.allowed} → gone`);
+  for (const r of result.lowered) L.push(`  ~ ${r.file}  ${r.rule}  ${r.allowed} → ${r.count}`);
+  if (!L.length) L.push("  (nothing to remove — every entry still has findings behind it)");
+  L.push("");
+  L.push(`${result.removed.length} entry(ies) removed, ${result.lowered.length} lowered, ${result.unchanged} unchanged.`);
+  L.push(`gyde-allowance.json: ${result.before} → ${result.after} findings. This ledger got SHORTER.`);
+  return L.join("\n");
+}
+
 /**
  * Compare a fresh scan against the ledger.
  *
@@ -161,25 +288,43 @@ export function compare(findings, ledger) {
 
   const failures = [];
   const cleared = [];
-  const adopted = [];
+  const newRules = new Set();
   let unchanged = 0;
 
   for (const [file, rules] of Object.entries(current)) {
     for (const [rule, count] of Object.entries(rules)) {
       const budget = allowed[file]?.[rule];
 
-      // G-68. A rule this ledger was never measured against did not exist when
-      // the measurement was taken, so its hits are pre-existing debt rather
-      // than something this change introduced. Recording them is CHARTER §4
-      // working as written — debt enters as a recorded allowance, never as zero
-      // by declaration — and it is what contract.md §5.2 promises a customer:
-      // a new rule arrives as an allowance-backed ratchet, not a red build.
+      // G-108. A rule this ledger does not name is NEW, and a new rule fails.
       //
-      // This deliberately does NOT weaken the delete-not-zero guarantee. A rule
-      // the ledger knows about, with an entry that has been cleared, is still
-      // absent from `allowed` and still fails below.
+      // G-68 made this branch adopt: it recorded the hits as pre-existing debt
+      // and let the build stay green, reading contract.md §5.2 as a promise
+      // that a new rule never turns a customer red. That was the wrong half of
+      // the sentence. `optional-prop` shipped after one consumer's baseline and
+      // was absorbed on every run — 173 findings across 80 files, announced in
+      // the log and counted by nobody — while CI stayed green and the ledger on
+      // disk stopped describing what the gate enforced. A ratchet that adopts
+      // is not a ratchet; it is a ledger that grows on a schedule set by
+      // somebody else's release.
+      //
+      // The promise §5.2 actually has to keep is that the product is not
+      // ambushed, and a failure with a one-command remedy keeps it. Recording
+      // is still available and still allowance-backed — it is now an act
+      // somebody performs (`gate --record-new-rules`) rather than a side effect
+      // of running the gate. Either way it is a decision on the record, which
+      // is the difference between CHARTER §4 and amnesty.
+      //
+      // `known` is still consulted, because *why* an entry is missing is worth
+      // saying: a rule the ledger names, cleared and re-added, is a different
+      // conversation from a rule that has never been measured here.
       if (budget === undefined && !known.rules.has(rule)) {
-        adopted.push({ file, rule, count, inferred: known.inferred });
+        newRules.add(rule);
+        failures.push({
+          file, rule, count, allowed: 0, kind: "unrecorded-rule",
+          inferred: known.inferred,
+          why: `\`${rule}\` is not named in this ledger's \`rules\`, so it is new to this ledger. ` +
+            "Fix these findings, or record them deliberately with `gate --record-new-rules`.",
+        });
         continue;
       }
 
@@ -218,7 +363,15 @@ export function compare(findings, ledger) {
     }
   }
 
-  return { ok: failures.length === 0, failures, cleared, adopted, unchanged };
+  return {
+    ok: failures.length === 0,
+    failures, cleared, unchanged,
+    // The rules this scan ran that the ledger does not name. Reported as a set
+    // rather than left to be re-derived from `failures`, because the remedy is
+    // per-rule ("record these two") while the failures are per-file-per-rule.
+    newRules: [...newRules].sort(),
+    inferredRuleSet: known.inferred,
+  };
 }
 
 /**
@@ -250,7 +403,7 @@ export function gate(scopes) {
     ok: results.every((r) => r.ok),
     results,
     failures: results.flatMap((r) => r.failures.map((f) => ({ ...f, scope: r.scope }))),
-    adopted: results.flatMap((r) => (r.adopted || []).map((a) => ({ ...a, scope: r.scope }))),
+    newRules: [...new Set(results.flatMap((r) => r.newRules || []))].sort(),
     unmeasured: results.filter((r) => r.unmeasured).map((r) => r.scope),
   };
 }
@@ -260,28 +413,35 @@ export function formatGate(verdict) {
   const L = [];
   for (const r of verdict.results) {
     if (r.unmeasured) { L.push(`✖ ${r.scope}: UNMEASURED — ${r.why}`); continue; }
-    if (r.ok && r.cleared.length === 0 && (r.adopted || []).length === 0) {
-      L.push(`✔ ${r.scope}: held (${r.unchanged} allowed entries unchanged)`); continue;
-    }
     if (r.ok && r.cleared.length === 0) { L.push(`✔ ${r.scope}: held (${r.unchanged} allowed entries unchanged)`); continue; }
-    if (r.ok) { L.push(`✔ ${r.scope}: held, and ${r.cleared.length} entry(ies) improved — commit the ledger to keep the ground`); continue; }
+    // G-113. This used to say "commit the ledger to keep the ground", which was
+    // true until G-108 removed the write and left the instruction pointing at
+    // it. A message naming a mechanism that no longer exists is worse than no
+    // message: it reads as free progress somebody forgot to collect, and the
+    // only way to act on it was to delete the ledger and re-record — the one
+    // operation the ratchet exists to prevent.
+    if (r.ok) {
+      L.push(`✔ ${r.scope}: held, and ${r.cleared.length} entry(ies) improved — \`gate --trim\` takes that ground`);
+      continue;
+    }
     L.push(`✖ ${r.scope}: ${r.failures.length} failure(s)`);
     for (const f of r.failures.slice(0, 10)) L.push(`    ${f.file}  ${f.rule}  ${f.why}`);
     if (r.failures.length > 10) L.push(`    … and ${r.failures.length - 10} more`);
   }
-  // Adoption is reported at the volume of a failure without being one. A rule
-  // that arrives, records silently and is never mentioned is a rule the product
-  // never learns it now has — and an unmentioned allowance is the to-do list
-  // nobody reads that LEDGER_NOTE exists to prevent.
-  if ((verdict.adopted || []).length) {
-    const byRule = {};
-    for (const a of verdict.adopted) (byRule[a.rule] ??= []).push(a);
-    L.push("", `${verdict.adopted.length} entry(ies) adopted for ${Object.keys(byRule).length} rule(s) this ledger predates:`);
-    for (const [rule, entries] of Object.entries(byRule)) {
-      const n = entries.reduce((s, e) => s + e.count, 0);
-      L.push(`    ${rule}: ${n} across ${entries.length} file(s) — recorded as existing debt, not judged`);
-    }
-    L.push("    Commit gyde-allowance.json, or the next run adopts them again and the rule never ratchets.");
+  // G-108. The remedy, printed with the failure, because a red build whose fix
+  // is "read the source of the gate" is the ambush contract.md §5.2 forbids.
+  // This is the whole difference between failing and being unusable.
+  if ((verdict.newRules || []).length) {
+    const rules = verdict.newRules;
+    L.push("", `${rules.length} rule(s) this ledger does not name: ${rules.join(", ")}`);
+    L.push("    A rule the ledger does not name is NEW, and a new rule fails rather than being absorbed.");
+    L.push("    Either fix the findings above, or record them as existing debt on purpose:");
+    L.push("");
+    L.push("        npx gyde design gate . --record-new-rules");
+    L.push("");
+    L.push("    That writes gyde-allowance.json and still exits non-zero — it records a");
+    L.push("    baseline for these rules rather than judging one, so the decision lands in a");
+    L.push("    diff somebody reviews. Every other number in the ledger is left alone.");
   }
   if (verdict.unmeasured.length) {
     L.push("", `${verdict.unmeasured.length} scope(s) could not be measured. That is a failure, not a pass.`);

package/ruleindex.mjs

@@ -0,0 +1,138 @@
+/**
+ * G-127 — every rule Gyde enforces, as data.
+ *
+ * ===========================================================================
+ * WHAT THIS IS FOR
+ * ===========================================================================
+ *
+ * A rule id reaches a customer in three places — a finding, the `rules` stamp
+ * in `gyde-allowance.json`, and a failing gate — and in all three it is a bare
+ * slug. `optional-prop` says what matched. It does not say what the rule is
+ * defending, or what the fix looks like, and both of those lived only in a
+ * module comment inside this repository, which the person reading the failure
+ * does not have.
+ *
+ * So: one machine-readable index, for a consuming repository's docs, an agent
+ * briefing itself on a finding, or a person who typed `gate` and got a slug.
+ *
+ * ===========================================================================
+ * IT DESCRIBES. IT DOES NOT DECIDE.
+ * ===========================================================================
+ *
+ * Nothing here is consulted by `scan`, `run`, `coverage` or the ledger, and
+ * nothing here may become so. A description that can change a verdict is a
+ * second implementation of the rule, kept in prose, and it will disagree with
+ * the first one silently. The `test` predicates stay in `rules.mjs`,
+ * `props.mjs`, `compound.mjs` and `docdrift.mjs`, where they are the only copy.
+ *
+ * The consequence to respect when editing: getting a sentence here wrong
+ * misleads a reader. Getting a predicate there wrong changes what fails. They
+ * are different kinds of mistake and they are deliberately in different files.
+ *
+ * ===========================================================================
+ * COMPLETENESS IS CHECKED, IN BOTH DIRECTIONS
+ * ===========================================================================
+ *
+ * `ruleindex.test.mjs` runs a real scan and compares its `rulesRun` stamp
+ * against the ids below. A rule implemented and not described fails; a rule
+ * described and not implemented fails too. The second direction matters as much
+ * as the first: an index naming a rule nobody runs is exactly the "all clear
+ * printed over unread data" shape, and it would read as coverage.
+ */
+
+import { RULES_BY_ID } from "./rules.mjs";
+
+/**
+ * The declaration rules' `intent` is READ FROM `rules.mjs` rather than restated.
+ *
+ * Two sentences about one rule is two sentences that can disagree, and the one
+ * a reader believes is whichever they found first.
+ */
+const summaryOf = (id) => {
+  const rule = RULES_BY_ID.get(id);
+  if (!rule) throw new Error(`ruleindex names ${id}, which rules.mjs does not declare`);
+  return rule.summary;
+};
+
+const ENTRIES = [
+  {
+    id: "untokenised-radius",
+    name: "Untokenised radius",
+    intent: summaryOf("untokenised-radius"),
+    fix: "Replace the literal with the dictionary's radius token — card, control or pill.",
+  },
+  {
+    id: "untokenised-space",
+    name: "Untokenised spacing",
+    intent: summaryOf("untokenised-space"),
+    fix: "Take the nearest step from the spacing scale; if none fits, the scale is the thing to change.",
+  },
+  {
+    id: "untokenised-type",
+    name: "Untokenised type size",
+    intent: summaryOf("untokenised-type"),
+    fix: "Use a type role rather than a size — the role is the decision, the pixels are its consequence.",
+  },
+  {
+    id: "untokenised-colour",
+    name: "Untokenised colour",
+    intent: summaryOf("untokenised-colour"),
+    fix: "Use a semantic colour token (text, border, raised, accent, danger …), not a palette entry or a literal.",
+  },
+  {
+    id: "arbitrary-shadow",
+    name: "Arbitrary shadow",
+    intent: summaryOf("arbitrary-shadow"),
+    fix: "Use the dictionary's elevation, or argue for a new one — depth is a semantic decision, not a garnish.",
+  },
+  {
+    id: "optional-prop",
+    name: "Optional prop",
+    intent: "A prop a caller may omit, leaving the component to make the decision silently.",
+    fix: "Make it required. Where absence is itself a real answer, make it required and NULLABLE " +
+         "(`describedBy: string | null`) and supply the ordinary value from the package's defaults " +
+         "module, spread at the call site. Do not reach for `x !== undefined` afterwards — see " +
+         "required-nullable-guard.",
+  },
+  {
+    id: "required-nullable-guard",
+    name: "Always-true undefined guard",
+    intent: "A guard comparing a required prop against `undefined`, which it can never be.",
+    fix: "Compare against null, or use `??` / `?.` — both test null and undefined, so they stay " +
+         "correct across exactly the change that breaks the explicit comparison.",
+  },
+  {
+    id: "compound-part-without-root",
+    name: "Orphaned compound part",
+    intent: "A compound component's part used without the root that supplies its context.",
+    fix: "Render the part inside its root, or use the wrapper that does.",
+  },
+  {
+    id: "stale-source-path",
+    name: "Stale path in documentation",
+    intent: "A path named in prose that no longer exists in the repository.",
+    fix: "Point it at the file that exists now, or delete the sentence — a path that does not resolve " +
+         "is read as a file somebody deleted by mistake.",
+  },
+];
+
+/** Frozen, because a caller mutating the shared index would change what every later caller reads. */
+const FROZEN = Object.freeze(ENTRIES.map((e) => Object.freeze({ ...e })));
+
+/**
+ * Every rule, as `{ id, name, intent, fix }`, sorted by id.
+ *
+ * Sorted rather than source-ordered so a consumer diffing two versions sees the
+ * rules that changed rather than the rules that moved.
+ */
+export function rules() {
+  return [...FROZEN].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** The same thing as a JSON string, for anything that is not JavaScript. */
+export function rulesJson() {
+  return JSON.stringify(rules(), null, 2) + "\n";
+}
+
+/** `node packages/design/ruleindex.mjs` prints it. */
+if (process.argv[1] && process.argv[1].endsWith("ruleindex.mjs")) process.stdout.write(rulesJson());

package/rules.mjs

@@ -112,6 +112,14 @@ export const RULES_BY_ID = new Map(RULES.map((r) => [r.id, r]));
  * other. That is the point of the whole module: if `untokenised-radius` is
  * tested only against `border-radius: 8px`, it is being validated against
  * exactly the rule we are trying not to write again.
+ *
+ * G-110 added a PROSE entry to every rule's `good` list. Each rule reads the
+ * normalised form, but the normaliser reads source text, and it was reading
+ * English sentences inside string literals as if they were class attributes —
+ * `"parks renderer shadow map must be enabled"` scored as `arbitrary-shadow`
+ * against a Node assertion harness with no markup in it. A test that only
+ * asserts real violations are caught cannot tell a precise rule from an eager
+ * one, so the prose fixtures are the half that was missing.
  */
 export const FIXTURES = {
   "untokenised-radius": {
@@ -127,6 +135,8 @@ export const FIXTURES = {
       { css: ".a { border-radius: 0 }" },
       { source: "const s = { borderRadius: radius.control }", filename: "a.ts" },
       { source: '<div className="rounded-card" />', filename: "a.tsx" },     // project semantic radius
+      // G-110. Prose, not markup: an English sentence naming a radius is not a radius.
+      { source: 'assert(ok, "the rounded-lg corner is wrong here");', filename: "a.mjs" },
     ],
   },
   "untokenised-space": {
@@ -140,6 +150,8 @@ export const FIXTURES = {
       { css: ".a { padding: var(--space-3) }" },
       { css: ".a { padding: 0 var(--space-2) }" },
       { css: ".a { margin: 0 }" },
+      { source: 'assert(ok, "the p-4 spacing is wrong here");', filename: "a.mjs" },
+      { source: 'assert(ok, "set padding: 12px on the container");', filename: "a.mjs" },
     ],
   },
   "untokenised-type": {
@@ -151,6 +163,7 @@ export const FIXTURES = {
     good: [
       { css: ".a { font-size: var(--text-body) }" },
       { source: "const s = { fontSize: text.body }", filename: "a.ts" },
+      { source: 'assert(ok, "the text-3xl heading must be present");', filename: "a.mjs" },
     ],
   },
   "untokenised-colour": {
@@ -167,6 +180,7 @@ export const FIXTURES = {
       { source: '<div className="bg-primary" />', filename: "a.tsx" },        // shadcn semantic utility
       { source: '<div className="text-muted-foreground" />', filename: "a.tsx" },
       { css: ":root { --color-surface: #0b0d10 }" },                          // a second palette, legitimately
+      { source: 'assert(ok, "expected background: #ffffff to be applied");', filename: "a.mjs" },
     ],
   },
   "arbitrary-shadow": {
@@ -177,6 +191,9 @@ export const FIXTURES = {
     good: [
       { css: ".a { box-shadow: var(--shadow-overlay) }" },
       { css: ".a { box-shadow: none }" },
+      // G-110, verbatim from the harness that produced four false findings.
+      { source: 'includes("parksCanvas", "gl.shadowMap.enabled = true", "parks renderer shadow map must be enabled");', filename: "a.mjs" },
+      { source: 'includes("nativeShadows", "receiveShadow = true", "parks tile meshes must receive shadows");', filename: "a.mjs" },
     ],
   },
 };

package/scope.mjs

@@ -0,0 +1,195 @@
+/**
+ * G-123 — `design.scope`, validated.
+ *
+ * WHAT WAS WRONG.
+ *
+ * `design.scope` reads as a guard and guarded nothing. A consumer could set it
+ * to `@definitely-not-a-scope`, and the gate exited 0 with byte-identical
+ * output — measured in a consuming repository, 2026-09-15. The key was
+ * read in exactly one place, `buildEmission`, which runs on `init`, `plan` and
+ * `upgrade`. The command a consumer wires into CI — `gate` — never looked at it.
+ *
+ * That is this repository's signature defect: a configuration key that a reader
+ * takes for a declaration Gyde checks, when nothing checks it. The value is not
+ * inert, either. It names the packages the emitted code imports, so a wrong one
+ * produces a scaffold whose every import resolves to nothing — and the first
+ * proof of that is a build failure in somebody else's repository.
+ *
+ * TWO CHECKS, AND THEY ARE DIFFERENT KINDS.
+ *
+ * `validateScopeShape` is a SCHEMA check. It asks whether the value is a
+ * package scope at all, needs nothing but the string, and therefore runs
+ * wherever the config is read — including `init` on a greenfield repository
+ * that has no packages yet.
+ *
+ * `checkScopeAgreement` is a MEASUREMENT. It asks whether the declared scope
+ * matches what the repository actually contains, so it needs the workspace and
+ * it only runs on the check path.
+ *
+ * WHY AGREEMENT DOES NOT SIMPLY REFUSE AN UNUSED SCOPE.
+ *
+ * Because "no package uses this scope" has two causes that must not render the
+ * same (CHARTER §5). A workspace whose packages are `@acme/*` and whose
+ * config says `@definitely-not-a-scope` is CONTRADICTED — there is evidence and
+ * the evidence disagrees. A workspace whose packages are all unscoped is
+ * UNMEASURED — `workspace.mjs` documents that case as the exact reason the
+ * override exists ("a project with no scope at all … needs to say which it
+ * wants"), and refusing it would fail the one config that has to declare a
+ * scope because nothing can be detected.
+ *
+ * So this refuses on contradiction and reports on absence, and says which one
+ * it did. A check that failed on absence would be a check that fails a correct
+ * config, which is how a gate gets switched off.
+ *
+ * THE DESIGN PACKAGE'S OWN NAME OUTRANKS THE HEADCOUNT.
+ *
+ * `detectScope` takes the most common scope, which is the right guess when
+ * guessing. It is the wrong authority here: the scope exists to name the
+ * emitted design packages, so if `packages/design-system` is called
+ * `@acme/design-system`, that is what `design.scope` has to be, however many
+ * `@vendor/*` packages sit beside it.
+ */
+
+/**
+ * A package scope, by npm's own rules for the part before the slash.
+ *
+ * npm lowercases scopes and forbids a leading dot or underscore. This is
+ * deliberately not a loose `^@\S+$`: the value is concatenated into a package
+ * name that has to be installable, and `@Acme` is not.
+ */
+export const SCOPE_PATTERN = /^@[a-z0-9-~][a-z0-9-._~]*$/;
+
+/**
+ * Is this a package scope?
+ *
+ * Absent is fine — the workspace's own scope is detected when the key is not
+ * declared, which is the documented default. Present and wrong is not fine, and
+ * the distinction is the whole point of the `declared` flag.
+ *
+ * @param {unknown} scope
+ * @returns {{ ok: boolean, declared: boolean, error: string|null }}
+ */
+export function validateScopeShape(scope) {
+  if (scope === undefined || scope === null) {
+    return { ok: true, declared: false, error: null };
+  }
+  if (typeof scope !== "string") {
+    return {
+      ok: false,
+      declared: true,
+      error: `design.scope must be a string like "@acme" (got ${JSON.stringify(scope)})`,
+    };
+  }
+  if (!SCOPE_PATTERN.test(scope)) {
+    const hint = scope.startsWith("@")
+      ? scope.includes("/")
+        ? ` — it is the scope alone, not a package name: use "${scope.split("/")[0]}"`
+        : ` — a scope is lowercase and may not start with "." or "_"`
+      : ` — a scope starts with "@": did you mean "@${scope}"?`;
+    return {
+      ok: false,
+      declared: true,
+      error: `design.scope must be a package scope like "@acme" (got ${JSON.stringify(scope)})${hint}`,
+    };
+  }
+  return { ok: true, declared: true, error: null };
+}
+
+/** The scope part of a package name, or null when the name is unscoped. */
+export function scopeOf(name) {
+  const m = (typeof name === "string" ? name : "").match(/^(@[^/]+)\//);
+  return m ? m[1] : null;
+}
+
+/**
+ * Does the declared scope agree with the repository?
+ *
+ * @param {object} opts
+ * @param {string|null|undefined} opts.declared        `design.scope` as committed
+ * @param {{path: string, name: string|null}[]} opts.packages   the discovered workspace
+ * @param {string} opts.systemPath                     where the design system lives
+ * @param {string|null} [opts.systemPackageName]       that package's own `name`, read from disk
+ * @returns {{ ok: boolean, measured: boolean, why: string, against: string|null }}
+ */
+export function checkScopeAgreement({ declared, packages = [], systemPath, systemPackageName = null }) {
+  const shape = validateScopeShape(declared);
+  if (!shape.declared) {
+    return {
+      ok: true,
+      measured: false,
+      why: "no design.scope is declared — the workspace's own scope is detected instead",
+      against: null,
+    };
+  }
+  // A malformed value never reaches here in the CLI (the config read refuses
+  // first), but a caller that skipped that must not be told the scope agrees.
+  if (!shape.ok) {
+    return { ok: false, measured: true, why: shape.error, against: "the schema" };
+  }
+
+  // The design package's own name is the authority when it exists, because the
+  // scope's entire job is to name that package.
+  const own = scopeOf(systemPackageName);
+  if (own) {
+    if (own === declared) {
+      return {
+        ok: true,
+        measured: true,
+        why: `the design package at ${systemPath} is named "${systemPackageName}"`,
+        against: systemPackageName,
+      };
+    }
+    return {
+      ok: false,
+      measured: true,
+      why: `design.scope is "${declared}", but the design package at ${systemPath} is named ` +
+        `"${systemPackageName}" — scope "${own}". The emitted code imports "${declared}/design-system", ` +
+        `which is not what that package is called, so those imports resolve to nothing.`,
+      against: systemPackageName,
+    };
+  }
+
+  const inUse = new Map();
+  for (const p of packages) {
+    const s = scopeOf(p?.name);
+    if (s) inUse.set(s, (inUse.get(s) ?? 0) + 1);
+  }
+
+  if (inUse.size === 0) {
+    return {
+      ok: true,
+      measured: false,
+      why: `no package in this workspace uses a scope, so "${declared}" could not be contradicted. ` +
+        `This is NOT a pass for the value — it is the absence of evidence either way.`,
+      against: null,
+    };
+  }
+
+  if (!inUse.has(declared)) {
+    const listed = [...inUse.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .map(([s, n]) => `${s} (${n} package(s))`)
+      .join(", ");
+    return {
+      ok: false,
+      measured: true,
+      why: `design.scope is "${declared}", but no package in this workspace uses it. ` +
+        `In use here: ${listed}.`,
+      against: listed,
+    };
+  }
+
+  return {
+    ok: true,
+    measured: true,
+    why: `${inUse.get(declared)} package(s) in this workspace use "${declared}"`,
+    against: `${inUse.get(declared)} package(s)`,
+  };
+}
+
+/** The gate's line for this check, carrying its denominator either way. */
+export function formatScope(r) {
+  if (!r.ok) return [`✖ design.scope: ${r.why}`, "", "Fix the value in gyde.config.json, or rename the package it names."].join("\n");
+  if (!r.measured) return `ℹ design.scope: ${r.why}`;
+  return `✔ design.scope: agrees — ${r.why}`;
+}