@litfamily/litgrok 1.0.0

package/.grok/skills/frontend-ui-ux/scripts/design-contract-rules.mjs

@@ -0,0 +1,361 @@
+// Front door for litfamily.design-contract/v1alpha1.
+//
+// A contract binds exactly two kinds of immutable identity: one `source_hash` for the
+// revision under design, and one `sha256` for each reference it declares. It owes nothing to
+// any other packaged artifact and requires no retrieval step before it can be validated.
+//
+// Rules are collected rather than thrown so a single run reports every defect. Callers that
+// only need a yes/no answer use validateDesignContractValue.
+import { UiuxContractError } from "./errors.mjs";
+import {
+  canonicalDesignContract,
+  ID_PREFIXES,
+  isLowercaseSha256,
+  isPrefixedId,
+  readDesignContract,
+} from "./design-contract-format.mjs";
+import {
+  collectInventoryIssues,
+  designContractInventoryEntries,
+} from "./design-contract-inventory-rules.mjs";
+import { collectSurfaceIssues, isObject } from "./design-contract-surface-rules.mjs";
+
+export const DESIGN_SCHEMA = "litfamily.design-contract/v1alpha1";
+export const DESIGN_SCHEMA_BETA = "litfamily.design-contract/v1beta1";
+export const DESIGN_SCHEMA_BETA2 = "litfamily.design-contract/v1beta2";
+
+// Exactly twelve root keys, in the order a reviewer reads them: identity, intent, direction,
+// the finite surface, the four quality budgets, the evidence policy, and the two places where
+// something is knowingly left undone.
+const DESIGN_CONTRACT_ROOT_KEYS = Object.freeze([
+  "schema_id", "contract_id", "source_hash", "intent", "direction", "inventory",
+  "accessibility", "localization", "performance", "evidence_policy", "omissions",
+  "accepted_exceptions",
+]);
+const DESIGN_CONTRACT_BETA_ROOT_KEYS = Object.freeze([
+  ...DESIGN_CONTRACT_ROOT_KEYS,
+  "lane",
+  "tokens",
+  "component_behaviors",
+  "responsive_transformations",
+  "motion",
+  "acceptance_criteria",
+]);
+// v1beta2 adds one optional root key. Optional is the whole point: a contract that says nothing
+// about taste is complete, and a v1beta1 document keeps validating byte-for-byte.
+const DESIGN_CONTRACT_BETA2_OPTIONAL_KEYS = Object.freeze(["taste"]);
+
+// Direction expressed as numbers a reviewer can argue with, rather than adjectives they cannot.
+const TASTE_DIALS = Object.freeze(["variance", "motion", "density"]);
+
+const LANES = new Set(["new-build", "brownfield", "redesign", "reference-fidelity", "design-system"]);
+const TOKEN_CATEGORIES = new Set(["color", "typography", "spacing", "radius", "shadow", "motion", "other"]);
+const MOTION_POLICIES = new Set(["none", "functional", "expressive"]);
+const VERIFICATION_METHODS = new Set([
+  "tests", "browser", "keyboard", "accessibility-tree", "screen-reader", "performance",
+  "localization", "manual",
+]);
+
+export {
+  canonicalDesignContract,
+  designContractInventoryEntries,
+  readDesignContract,
+};
+
+function collectIdentityIssues(contract, issues) {
+  if (![DESIGN_SCHEMA, DESIGN_SCHEMA_BETA, DESIGN_SCHEMA_BETA2].includes(contract.schema_id)) {
+    issues.push({
+      code: "DESIGN_CONTRACT_SCHEMA_ID",
+      path: "schema_id",
+      message: `schema_id must equal one of ${[DESIGN_SCHEMA, DESIGN_SCHEMA_BETA, DESIGN_SCHEMA_BETA2].join(", ")}`,
+    });
+  }
+  if (!isPrefixedId(contract.contract_id, ID_PREFIXES.contract)) {
+    issues.push({
+      code: "DESIGN_CONTRACT_ID_PREFIX",
+      path: "contract_id",
+      message: `contract_id must be a typed identifier starting with ${ID_PREFIXES.contract}`,
+    });
+  }
+  if (!isLowercaseSha256(contract.source_hash)) {
+    issues.push({
+      code: "DESIGN_CONTRACT_HASH_GRAMMAR",
+      path: "source_hash",
+      message: "source_hash must be 64 lowercase hexadecimal digits",
+    });
+  }
+}
+
+function addIssue(issues, code, path, message) {
+  issues.push({ code, path, message });
+}
+
+function exactObject(value, allowed, path, issues) {
+  if (!isObject(value)) {
+    addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", path, `${path} must be an object`);
+    return false;
+  }
+  const missing = allowed.filter((key) => !Object.hasOwn(value, key));
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (missing.length > 0) addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", path, `${path} is missing ${missing.join(", ")}`);
+  if (unknown.length > 0) addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", path, `${path} declares unknown keys ${unknown.join(", ")}`);
+  return missing.length === 0;
+}
+
+function records(value, path, issues, { minimum = 0, maximum = Number.POSITIVE_INFINITY } = {}) {
+  if (!Array.isArray(value)) {
+    addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", path, `${path} must be an array`);
+    return [];
+  }
+  if (value.length < minimum) addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", path, `${path} must list at least ${minimum} entries`);
+  if (value.length > maximum) addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", path, `${path} must list at most ${maximum} entries`);
+  return value.filter((item, index) => {
+    if (isObject(item)) return true;
+    addIssue(issues, "DESIGN_CONTRACT_BETA_SHAPE", `${path}[${index}]`, `${path}[${index}] must be an object`);
+    return false;
+  });
+}
+
+function requiredText(value, path, issues) {
+  if (typeof value !== "string" || Array.from(value).length > 512
+    || !/^\S(?:[^\n\r\t]*\S)?$/u.test(value)) {
+    addIssue(issues, "DESIGN_CONTRACT_BETA_TEXT", path, `${path} must be bounded one-line text`);
+    return false;
+  }
+  return true;
+}
+
+function declaredIds(contract, category) {
+  const values = contract.inventory?.[category];
+  if (!Array.isArray(values)) return new Set();
+  return new Set(values.filter(isObject).map((item) => item.id).filter((id) => typeof id === "string"));
+}
+
+function references(value, path, prefix, declared, issues) {
+  if (!Array.isArray(value) || value.length === 0) {
+    addIssue(issues, "DESIGN_CONTRACT_BETA_REFERENCE", path, `${path} must list at least one ${prefix}`);
+    return;
+  }
+  if (value.length > 64) {
+    addIssue(issues, "DESIGN_CONTRACT_BETA_REFERENCE", path, `${path} must list at most 64 ${prefix} references`);
+  }
+  if (new Set(value).size !== value.length) addIssue(issues, "DESIGN_CONTRACT_BETA_REFERENCE", path, `${path} must be unique`);
+  for (const id of value) {
+    if (!isPrefixedId(id, `${prefix}:`)) addIssue(issues, "DESIGN_CONTRACT_BETA_REFERENCE", path, `${String(id)} must use the ${prefix}: prefix`);
+    else if (!declared.has(id)) addIssue(issues, "DESIGN_CONTRACT_BETA_REFERENCE", path, `${id} is not a declared ${prefix}`);
+  }
+}
+
+function collectBetaIssues(contract, issues) {
+  const ids = [];
+  if (!LANES.has(contract.lane)) addIssue(issues, "DESIGN_CONTRACT_BETA_LANE", "lane", "lane must name a supported operating lane");
+  const routes = declaredIds(contract, "routes");
+  const components = declaredIds(contract, "components");
+  const interactions = declaredIds(contract, "interactions");
+  const states = declaredIds(contract, "states");
+  const viewports = declaredIds(contract, "viewports");
+  const inventoryIds = new Set([
+    ...routes, ...declaredIds(contract, "regions"), ...components, ...interactions, ...states,
+    ...viewports, ...declaredIds(contract, "references"),
+  ]);
+  if (!Array.isArray(contract.inventory?.viewports) || contract.inventory.viewports.length < 2) {
+    addIssue(issues, "DESIGN_CONTRACT_BETA_VIEWPORTS", "inventory.viewports", "beta contracts must declare at least two viewport bounds");
+  }
+
+  for (const [index, token] of records(contract.tokens, "tokens", issues, { minimum: 1, maximum: 256 }).entries()) {
+    const path = `tokens[${index}]`;
+    exactObject(token, ["id", "category", "value", "usage"], path, issues);
+    if (!isPrefixedId(token.id, "token:")) addIssue(issues, "DESIGN_CONTRACT_BETA_TOKEN", `${path}.id`, "token id must use the token: prefix");
+    else ids.push(token.id);
+    if (!TOKEN_CATEGORIES.has(token.category)) addIssue(issues, "DESIGN_CONTRACT_BETA_TOKEN", `${path}.category`, "token category is unsupported");
+    requiredText(token.value, `${path}.value`, issues);
+    requiredText(token.usage, `${path}.usage`, issues);
+  }
+
+  for (const [index, behavior] of records(contract.component_behaviors, "component_behaviors", issues, { minimum: 1, maximum: 512 }).entries()) {
+    const path = `component_behaviors[${index}]`;
+    exactObject(behavior, ["component_id", "state_ids", "interaction_ids", "keyboard_behavior"], path, issues);
+    if (!isPrefixedId(behavior.component_id, "component:")) addIssue(issues, "DESIGN_CONTRACT_BETA_COMPONENT", `${path}.component_id`, "component_id must use the component: prefix");
+    else if (!components.has(behavior.component_id)) addIssue(issues, "DESIGN_CONTRACT_BETA_COMPONENT", `${path}.component_id`, `${behavior.component_id} is not a declared component`);
+    references(behavior.state_ids, `${path}.state_ids`, "state", states, issues);
+    references(behavior.interaction_ids, `${path}.interaction_ids`, "interaction", interactions, issues);
+    requiredText(behavior.keyboard_behavior, `${path}.keyboard_behavior`, issues);
+  }
+
+  for (const [index, transformation] of records(contract.responsive_transformations, "responsive_transformations", issues, { minimum: 1, maximum: 256 }).entries()) {
+    const path = `responsive_transformations[${index}]`;
+    exactObject(transformation, ["route_id", "viewport_id", "behavior"], path, issues);
+    if (!isPrefixedId(transformation.route_id, "route:") || !routes.has(transformation.route_id)) addIssue(issues, "DESIGN_CONTRACT_BETA_RESPONSIVE", `${path}.route_id`, `${String(transformation.route_id)} is not a declared route`);
+    if (!isPrefixedId(transformation.viewport_id, "viewport:") || !viewports.has(transformation.viewport_id)) addIssue(issues, "DESIGN_CONTRACT_BETA_RESPONSIVE", `${path}.viewport_id`, `${String(transformation.viewport_id)} is not a declared viewport`);
+    requiredText(transformation.behavior, `${path}.behavior`, issues);
+  }
+
+  if (exactObject(contract.motion, ["policy", "reduced_motion_behavior", "transitions"], "motion", issues)) {
+    if (!MOTION_POLICIES.has(contract.motion.policy)) addIssue(issues, "DESIGN_CONTRACT_BETA_MOTION", "motion.policy", "motion.policy is unsupported");
+    requiredText(contract.motion.reduced_motion_behavior, "motion.reduced_motion_behavior", issues);
+    const transitions = records(contract.motion.transitions, "motion.transitions", issues, { maximum: 256 });
+    if (contract.motion.policy !== "none" && transitions.length === 0) addIssue(issues, "DESIGN_CONTRACT_BETA_MOTION", "motion.transitions", "active motion policy requires a transition");
+    if (contract.motion.policy === "none" && transitions.length > 0) addIssue(issues, "DESIGN_CONTRACT_BETA_MOTION", "motion.transitions", "motion policy none forbids transitions");
+    for (const [index, transition] of transitions.entries()) {
+      const path = `motion.transitions[${index}]`;
+      exactObject(transition, ["id", "interaction_id", "duration_ms", "easing"], path, issues);
+      if (!isPrefixedId(transition.id, "transition:")) addIssue(issues, "DESIGN_CONTRACT_BETA_MOTION", `${path}.id`, "transition id must use the transition: prefix");
+      else ids.push(transition.id);
+      if (!isPrefixedId(transition.interaction_id, "interaction:") || !interactions.has(transition.interaction_id)) addIssue(issues, "DESIGN_CONTRACT_BETA_MOTION", `${path}.interaction_id`, `${String(transition.interaction_id)} is not a declared interaction`);
+      if (!Number.isInteger(transition.duration_ms) || transition.duration_ms < 0 || transition.duration_ms > 10_000) addIssue(issues, "DESIGN_CONTRACT_BETA_MOTION", `${path}.duration_ms`, "duration_ms must be an integer from 0 through 10000");
+      requiredText(transition.easing, `${path}.easing`, issues);
+    }
+  }
+
+  for (const [index, criterion] of records(contract.acceptance_criteria, "acceptance_criteria", issues, { minimum: 1, maximum: 256 }).entries()) {
+    const path = `acceptance_criteria[${index}]`;
+    exactObject(criterion, ["id", "observable", "verification", "required", "inventory_ids"], path, issues);
+    if (!isPrefixedId(criterion.id, "criterion:")) addIssue(issues, "DESIGN_CONTRACT_BETA_CRITERION", `${path}.id`, "criterion id must use the criterion: prefix");
+    else ids.push(criterion.id);
+    requiredText(criterion.observable, `${path}.observable`, issues);
+    if (!VERIFICATION_METHODS.has(criterion.verification)) addIssue(issues, "DESIGN_CONTRACT_BETA_CRITERION", `${path}.verification`, "criterion verification is unsupported");
+    if (criterion.required !== true) addIssue(issues, "DESIGN_CONTRACT_BETA_CRITERION", `${path}.required`, "criterion required must be true");
+    if (!Array.isArray(criterion.inventory_ids) || criterion.inventory_ids.length === 0
+      || criterion.inventory_ids.length > 64
+      || criterion.inventory_ids.length !== new Set(criterion.inventory_ids).size) {
+      addIssue(issues, "DESIGN_CONTRACT_BETA_CRITERION", `${path}.inventory_ids`, "criterion must name 1 through 64 unique covered inventory ids");
+    } else for (const id of criterion.inventory_ids) if (!inventoryIds.has(id)) addIssue(issues, "DESIGN_CONTRACT_BETA_CRITERION", `${path}.inventory_ids`, `${String(id)} is not declared in contract inventory`);
+  }
+  return ids;
+}
+
+// Taste is reported one defect at a time. A reviewer fixing a dial wants the dial named, not a
+// list of every consequence of the same mistake.
+function collectTasteIssues(contract, issues) {
+  if (!Object.hasOwn(contract, "taste")) return;
+  const taste = contract.taste;
+  if (!isObject(taste)) {
+    addIssue(issues, "DESIGN_CONTRACT_TASTE", "taste", "taste must be an object");
+    return;
+  }
+  const unknown = Object.keys(taste).filter((key) => !TASTE_DIALS.includes(key));
+  if (unknown.length > 0) {
+    addIssue(issues, "DESIGN_CONTRACT_TASTE", "taste", `taste declares unknown dials ${unknown.join(", ")}`);
+    return;
+  }
+  for (const dial of TASTE_DIALS) {
+    const path = `taste.${dial}`;
+    if (!Object.hasOwn(taste, dial)) {
+      addIssue(issues, "DESIGN_CONTRACT_TASTE", path, `${path} is required whenever taste is declared`);
+      return;
+    }
+    if (!Number.isInteger(taste[dial]) || taste[dial] < 1 || taste[dial] > 10) {
+      addIssue(issues, "DESIGN_CONTRACT_TASTE", path, `${path} must be an integer from 1 through 10`);
+      return;
+    }
+  }
+}
+
+// Identifiers are unique across the whole document, not merely within a group. Two surfaces
+// that share an identifier cannot be told apart in an evidence record or a review receipt.
+function collectIdCollisionIssues(contract, issues) {
+  const declared = [
+    { path: "contract_id", id: contract.contract_id },
+    ...designContractInventoryEntries(contract).map(({ id, kind }) => ({ path: `inventory.${kind}`, id })),
+  ];
+  for (const field of ["omissions", "accepted_exceptions"]) {
+    if (!Array.isArray(contract[field])) continue;
+    contract[field].forEach((record, index) => {
+      if (isObject(record)) declared.push({ path: `${field}[${index}].id`, id: record.id });
+    });
+  }
+  const seen = new Set();
+  for (const { path, id } of declared) {
+    if (typeof id !== "string") continue;
+    if (seen.has(id)) {
+      issues.push({
+        code: "DESIGN_CONTRACT_ID_COLLISION",
+        path,
+        message: `${id} is declared more than once in this contract`,
+      });
+      continue;
+    }
+    seen.add(id);
+  }
+}
+
+export function collectDesignContractIssues(contract) {
+  const issues = [];
+  if (!isObject(contract)) {
+    return [{
+      code: "DESIGN_CONTRACT_NOT_OBJECT",
+      path: "",
+      message: "a Design Contract must be a JSON object",
+    }];
+  }
+  const beta2 = contract.schema_id === DESIGN_SCHEMA_BETA2;
+  const beta = beta2 || contract.schema_id === DESIGN_SCHEMA_BETA;
+  const requiredKeys = beta ? DESIGN_CONTRACT_BETA_ROOT_KEYS : DESIGN_CONTRACT_ROOT_KEYS;
+  const allowedKeys = beta2 ? [...requiredKeys, ...DESIGN_CONTRACT_BETA2_OPTIONAL_KEYS] : requiredKeys;
+  const missing = requiredKeys.filter((key) => !Object.hasOwn(contract, key));
+  const unknown = Object.keys(contract).filter((key) => !allowedKeys.includes(key));
+  if (missing.length > 0) {
+    issues.push({
+      code: "DESIGN_CONTRACT_ROOT_KEYS",
+      path: "",
+      message: `the contract is missing ${missing.join(", ")}`,
+    });
+  }
+  if (unknown.length > 0) {
+    issues.push({
+      code: "DESIGN_CONTRACT_ROOT_KEYS",
+      path: "",
+      message: `the contract declares unknown root keys ${unknown.join(", ")}`,
+    });
+  }
+  // Root keys must all be present before group rules can say anything meaningful.
+  if (missing.length > 0) return issues;
+  collectIdentityIssues(contract, issues);
+  collectSurfaceIssues(contract, issues);
+  collectInventoryIssues(contract, issues);
+  if (beta) {
+    collectTasteIssues(contract, issues);
+    const betaIds = collectBetaIssues(contract, issues);
+    const existingIds = new Set([
+      contract.contract_id,
+      ...designContractInventoryEntries(contract).map(({ id }) => id),
+      ...(Array.isArray(contract.omissions) ? contract.omissions.map(({ id }) => id) : []),
+      ...(Array.isArray(contract.accepted_exceptions)
+        ? contract.accepted_exceptions.map(({ id }) => id)
+        : []),
+    ]);
+    for (const id of betaIds) {
+      if (existingIds.has(id)) addIssue(issues, "DESIGN_CONTRACT_ID_COLLISION", "", `${id} is declared more than once in this contract`);
+      existingIds.add(id);
+    }
+  }
+  collectIdCollisionIssues(contract, issues);
+  return issues;
+}
+
+export function designContractReport(contract) {
+  const issues = collectDesignContractIssues(contract);
+  const beta2 = isObject(contract) && contract.schema_id === DESIGN_SCHEMA_BETA2;
+  const beta = beta2 || (isObject(contract) && contract.schema_id === DESIGN_SCHEMA_BETA);
+  const alpha = isObject(contract) && contract.schema_id === DESIGN_SCHEMA;
+  const valid = issues.length === 0;
+  return {
+    valid,
+    schema: beta2 ? DESIGN_SCHEMA_BETA2 : (beta ? DESIGN_SCHEMA_BETA : DESIGN_SCHEMA),
+    issues,
+    diagnostics: alpha ? ["LEGACY_SCHEMA_V1ALPHA1"] : [],
+    evidence_eligible: beta && valid,
+  };
+}
+
+// Throwing wrapper for callers that treat an invalid contract as an exception, such as the
+// evidence lane binding a contract to a manifest hash.
+export function validateDesignContractValue(contract) {
+  const issues = collectDesignContractIssues(contract);
+  if (issues.length === 0) return;
+  const [first] = issues;
+  throw new UiuxContractError(first.code, first.message, {
+    issue_count: issues.length,
+    issues,
+  });
+}

package/.grok/skills/frontend-ui-ux/scripts/design-contract-surface-rules.mjs

@@ -0,0 +1,313 @@
+// Non-inventory rule groups of litfamily.design-contract/v1alpha1.
+//
+// The JSON Schema document mirrors these rules for editors and reviewers, but a schema
+// document is inert: nothing in the runtime reads it. Every rule that must actually hold is
+// executed here and reported as a structured issue.
+import { isStableId, isUtcTimestamp } from "./design-contract-format.mjs";
+
+// A single literal target. Not a pattern and not an enum: the contract binds one conformance
+// target so that two contracts are comparable without interpreting a range.
+export const ACCESSIBILITY_TARGET = "WCAG 2.2 AA";
+
+export const TOKEN_STRATEGIES = Object.freeze(["reuse", "extend", "create"]);
+
+export const EVIDENCE_CHANNELS = Object.freeze([
+  "tests", "browser", "keyboard", "accessibility-tree", "screen-reader", "performance",
+  "localization",
+]);
+
+const ACCESSIBILITY_FLAGS = Object.freeze([
+  "keyboard", "screen_reader", "reduced_motion", "forced_colors",
+]);
+
+const LOCALIZATION_FLAGS = Object.freeze([
+  "cjk_line_break_review", "font_fallback_review", "ime_review", "rtl_review",
+]);
+
+const LOCALE_TAG = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/u;
+
+const TEXT_MAX_LENGTH = 512;
+
+const PHRASE_MAX_ITEMS = 32;
+
+const SCOPE_MAX_ITEMS = 64;
+
+export function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Trimmed, single-line, bounded. A field that needs a paragraph belongs in a reference
+// document, not in a machine-compared contract value.
+export function isText(value) {
+  if (typeof value !== "string") return false;
+  const length = Array.from(value).length;
+  return length > 0 && length <= TEXT_MAX_LENGTH && value.trim() === value
+    && !/[\n\r\t]/u.test(value);
+}
+
+export function isStrictBoolean(value) {
+  return typeof value === "boolean";
+}
+
+export function isBoundedInteger(value, minimum, maximum) {
+  return Number.isInteger(value) && value >= minimum && value <= maximum;
+}
+
+export function isBoundedNumber(value, minimum, maximum) {
+  return typeof value === "number" && Number.isFinite(value) && value >= minimum && value <= maximum;
+}
+
+function isPhraseList(value, { minimum, maximum = PHRASE_MAX_ITEMS }) {
+  return Array.isArray(value) && value.length >= minimum && value.length <= maximum
+    && value.length === new Set(value).size && value.every(isText);
+}
+
+function keySet(value, required, optional = []) {
+  if (!isObject(value)) return { missing: required, unknown: [] };
+  const allowed = new Set([...required, ...optional]);
+  return {
+    missing: required.filter((field) => !Object.hasOwn(value, field)),
+    unknown: Object.keys(value).filter((field) => !allowed.has(field)),
+  };
+}
+
+// Closed objects everywhere. An unknown key is a silent design decision nobody reviewed, so
+// it fails rather than being ignored.
+export function collectKeyIssues(issues, value, path, code, required, optional = []) {
+  if (!isObject(value)) {
+    issues.push({ code, path, message: `${path} must be an object` });
+    return false;
+  }
+  const { missing, unknown } = keySet(value, required, optional);
+  if (missing.length > 0) {
+    issues.push({ code, path, message: `${path} is missing ${missing.join(", ")}` });
+  }
+  if (unknown.length > 0) {
+    issues.push({ code, path, message: `${path} declares unknown keys ${unknown.join(", ")}` });
+  }
+  return missing.length === 0 && unknown.length === 0;
+}
+
+function collectIntentIssues(issues, intent) {
+  const code = "DESIGN_CONTRACT_INTENT";
+  if (!collectKeyIssues(issues, intent, "intent", code, [
+    "audiences", "tasks", "qualities", "constraints", "non_goals",
+  ])) return;
+  for (const field of ["audiences", "tasks", "qualities"]) {
+    if (!isPhraseList(intent[field], { minimum: 1 })) {
+      issues.push({
+        code,
+        path: `intent.${field}`,
+        message: `intent.${field} needs 1..${PHRASE_MAX_ITEMS} unique non-empty entries`,
+      });
+    }
+  }
+  for (const field of ["constraints", "non_goals"]) {
+    if (!isPhraseList(intent[field], { minimum: 0 })) {
+      issues.push({
+        code,
+        path: `intent.${field}`,
+        message: `intent.${field} must be an array of at most ${PHRASE_MAX_ITEMS} unique non-empty entries`,
+      });
+    }
+  }
+}
+
+function collectDirectionIssues(issues, direction) {
+  const code = "DESIGN_CONTRACT_DIRECTION";
+  if (!collectKeyIssues(issues, direction, "direction", code, [
+    "name", "principles", "token_strategy", "voice",
+  ])) return;
+  for (const field of ["name", "voice"]) {
+    if (!isText(direction[field])) {
+      issues.push({ code, path: `direction.${field}`, message: `direction.${field} must be one bounded line` });
+    }
+  }
+  // Three principles is the minimum that expresses a direction; more than seven is a wish
+  // list nobody can apply as a tie-breaker.
+  if (!isPhraseList(direction.principles, { minimum: 3, maximum: 7 })) {
+    issues.push({
+      code,
+      path: "direction.principles",
+      message: "direction.principles needs 3..7 unique non-empty entries",
+    });
+  }
+  if (!TOKEN_STRATEGIES.includes(direction.token_strategy)) {
+    issues.push({
+      code,
+      path: "direction.token_strategy",
+      message: `direction.token_strategy must be one of ${TOKEN_STRATEGIES.join(", ")}`,
+    });
+  }
+}
+
+function collectAccessibilityIssues(issues, accessibility) {
+  const code = "DESIGN_CONTRACT_ACCESSIBILITY";
+  if (!collectKeyIssues(issues, accessibility, "accessibility", code, [
+    "target", ...ACCESSIBILITY_FLAGS, "zoom_percent",
+  ])) return;
+  if (accessibility.target !== ACCESSIBILITY_TARGET) {
+    issues.push({
+      code,
+      path: "accessibility.target",
+      message: `accessibility.target must equal ${JSON.stringify(ACCESSIBILITY_TARGET)}`,
+    });
+  }
+  for (const flag of ACCESSIBILITY_FLAGS) {
+    if (!isStrictBoolean(accessibility[flag])) {
+      issues.push({
+        code,
+        path: `accessibility.${flag}`,
+        message: `accessibility.${flag} must be true or false, not a truthy value`,
+      });
+    }
+  }
+  if (!isBoundedInteger(accessibility.zoom_percent, 200, 400)) {
+    issues.push({
+      code,
+      path: "accessibility.zoom_percent",
+      message: "accessibility.zoom_percent must be an integer from 200 through 400",
+    });
+  }
+}
+
+function collectLocalizationIssues(issues, localization) {
+  const code = "DESIGN_CONTRACT_LOCALIZATION";
+  if (!collectKeyIssues(issues, localization, "localization", code, [
+    "locales", "text_expansion_percent", ...LOCALIZATION_FLAGS,
+  ])) return;
+  if (!isPhraseList(localization.locales, { minimum: 1 })
+    || !localization.locales.every((locale) => LOCALE_TAG.test(locale))) {
+    issues.push({
+      code,
+      path: "localization.locales",
+      message: "localization.locales needs at least one unique language tag such as ko-KR",
+    });
+  }
+  if (!isBoundedInteger(localization.text_expansion_percent, 0, 300)) {
+    issues.push({
+      code,
+      path: "localization.text_expansion_percent",
+      message: "localization.text_expansion_percent must be an integer from 0 through 300",
+    });
+  }
+  for (const flag of LOCALIZATION_FLAGS) {
+    if (!isStrictBoolean(localization[flag])) {
+      issues.push({
+        code,
+        path: `localization.${flag}`,
+        message: `localization.${flag} must be true or false, not a truthy value`,
+      });
+    }
+  }
+}
+
+// Every dimension is bounded on both sides. An open-ended budget is not a budget, and a
+// missing upper bound is how a regression gets accepted as "within contract".
+function collectPerformanceIssues(issues, performance) {
+  const code = "DESIGN_CONTRACT_PERFORMANCE";
+  if (!collectKeyIssues(issues, performance, "performance", code, [
+    "lcp_ms", "cls", "inp_ms", "initial_js_kb", "initial_css_kb",
+  ])) return;
+  for (const field of ["lcp_ms", "inp_ms"]) {
+    if (!isBoundedInteger(performance[field], 1, 60000)) {
+      issues.push({
+        code,
+        path: `performance.${field}`,
+        message: `performance.${field} must be an integer from 1 through 60000`,
+      });
+    }
+  }
+  if (!isBoundedNumber(performance.cls, 0, 1)) {
+    issues.push({
+      code,
+      path: "performance.cls",
+      message: "performance.cls must be a finite number from 0 through 1",
+    });
+  }
+  for (const field of ["initial_js_kb", "initial_css_kb"]) {
+    if (!isBoundedInteger(performance[field], 0, 1048576)) {
+      issues.push({
+        code,
+        path: `performance.${field}`,
+        message: `performance.${field} must be an integer from 0 through 1048576`,
+      });
+    }
+  }
+}
+
+function collectEvidencePolicyIssues(issues, policy) {
+  const code = "DESIGN_CONTRACT_EVIDENCE_POLICY";
+  if (!collectKeyIssues(issues, policy, "evidence_policy", code, [
+    "independent_review_required", "required_channels", "cleanup_required",
+  ])) return;
+  for (const field of ["independent_review_required", "cleanup_required"]) {
+    if (!isStrictBoolean(policy[field])) {
+      issues.push({
+        code,
+        path: `evidence_policy.${field}`,
+        message: `evidence_policy.${field} must be true or false, not a truthy value`,
+      });
+    }
+  }
+  const channels = policy.required_channels;
+  if (!Array.isArray(channels) || channels.length < 1
+    || channels.length > EVIDENCE_CHANNELS.length
+    || channels.length !== new Set(channels).size
+    || !channels.every((channel) => EVIDENCE_CHANNELS.includes(channel))) {
+    issues.push({
+      code,
+      path: "evidence_policy.required_channels",
+      message: `evidence_policy.required_channels must be a non-empty unique subset of ${EVIDENCE_CHANNELS.join(", ")}`,
+    });
+  }
+}
+
+// Omissions and accepted exceptions are the only places where a contract may leave something
+// undone, so both carry a named owner. `expires_at` is optional: an undated record is a
+// standing decision, and a dated one must be a strict UTC instant.
+function collectScopeRecordIssues(issues, records, field) {
+  const code = "DESIGN_CONTRACT_SCOPE_RECORD";
+  if (!Array.isArray(records) || records.length > SCOPE_MAX_ITEMS) {
+    issues.push({
+      code,
+      path: field,
+      message: `${field} must be an array of at most ${SCOPE_MAX_ITEMS} records`,
+    });
+    return;
+  }
+  records.forEach((record, index) => {
+    const path = `${field}[${index}]`;
+    if (!collectKeyIssues(issues, record, path, code, ["id", "reason", "owner"], ["expires_at"])) return;
+    if (!isStableId(record.id)) {
+      issues.push({
+        code: "DESIGN_CONTRACT_ID_GRAMMAR",
+        path: `${path}.id`,
+        message: `${path}.id must be a typed lowercase identifier`,
+      });
+    }
+    for (const key of ["reason", "owner"]) {
+      if (!isText(record[key])) {
+        issues.push({ code, path: `${path}.${key}`, message: `${path}.${key} must be one bounded line` });
+      }
+    }
+    if (Object.hasOwn(record, "expires_at") && !isUtcTimestamp(record.expires_at)) {
+      issues.push({
+        code: "DESIGN_CONTRACT_TIMESTAMP",
+        path: `${path}.expires_at`,
+        message: `${path}.expires_at must be a strict UTC instant such as 2026-08-01T00:00:00.000Z`,
+      });
+    }
+  });
+}
+
+export function collectSurfaceIssues(contract, issues) {
+  collectIntentIssues(issues, contract.intent);
+  collectDirectionIssues(issues, contract.direction);
+  collectAccessibilityIssues(issues, contract.accessibility);
+  collectLocalizationIssues(issues, contract.localization);
+  collectPerformanceIssues(issues, contract.performance);
+  collectEvidencePolicyIssues(issues, contract.evidence_policy);
+  collectScopeRecordIssues(issues, contract.omissions, "omissions");
+  collectScopeRecordIssues(issues, contract.accepted_exceptions, "accepted_exceptions");
+}