universal-dev-standards 6.14.0-beta.3 → 6.14.0-beta.5

package/src/utils/health-scorer.js

@@ -177,20 +177,26 @@ export function calculateConsistency(projectPath) {
 }
 
 /**
- * Calculate coverage score
+ * Calculate coverage score — how many of the two check scripts each installed standard can
+ * have (`scripts/check-<id>.sh`, `scripts/check-<id>-sync.sh`) are present.
+ *
+ * XSPEC-444 R5: this used to report `details.has_tests` and add it into the sum, but
+ * `hasTests` was declared as 0 and never incremented anywhere — a number that was always 0 and
+ * looked like a measurement of whether the standards have tests. It is removed rather than
+ * faked. The SCORE is unchanged: the denominator was already two per standard, which is the
+ * two script kinds above, so no project's coverage score moves.
  * @param {string} projectPath
  * @param {string[]} standardIds
  * @returns {{ score: number, details: object }}
  */
 export function calculateCoverage(projectPath, standardIds) {
   if (!standardIds || standardIds.length === 0) {
-    return { score: 0, details: { has_check_script: 0, has_tests: 0, total: 0 } };
+    return { score: 0, details: { has_check_script: 0, total: 0 } };
   }
 
   // Check for check scripts matching standard names
   const scriptsDir = join(projectPath, 'scripts');
   let hasCheckScript = 0;
-  let hasTests = 0;
 
   for (const id of standardIds) {
     const scriptName = `check-${id}.sh`;
@@ -204,16 +210,13 @@ export function calculateCoverage(projectPath, standardIds) {
     }
   }
 
-  const ratio = standardIds.length > 0
-    ? (hasCheckScript + hasTests) / (standardIds.length * 2)
-    : 0;
+  const ratio = hasCheckScript / (standardIds.length * 2);
   const score = Math.round(Math.min(ratio * 100, 100));
 
   return {
     score,
     details: {
       has_check_script: hasCheckScript,
-      has_tests: hasTests,
       total: standardIds.length
     }
   };

package/src/utils/locale.js

@@ -32,6 +32,24 @@ export function displayLanguageToLocale(displayLanguage) {
   return LOCALE_MAP[displayLanguage.toLowerCase()] || 'en';
 }
 
+/**
+ * Normalise a requested display language and say whether it is supported.
+ *
+ * `uds init --locale zh-CN` used to install English and exit 0: the value was compared case-sensitively
+ * further down, so the upper-case spelling silently missed every Chinese branch. An unsupported value such
+ * as `fr` did the same — English, exit 0, nothing said. The caller still falls back to English for an
+ * unsupported value, but now it can say so.
+ * @param {string|undefined|null} requested - what the user, install.yaml or the environment asked for
+ * @returns {{ displayLanguage: string|undefined|null, supported: boolean }}
+ */
+export function normalizeRequestedLocale(requested) {
+  if (typeof requested !== 'string' || requested.trim() === '') {
+    return { displayLanguage: requested, supported: true };
+  }
+  const displayLanguage = requested.trim().toLowerCase();
+  return { displayLanguage, supported: Object.prototype.hasOwnProperty.call(LOCALE_MAP, displayLanguage) };
+}
+
 /**
  * Check if a locale requires localized skill installation.
  * English locale uses the default source, no localization needed.
@@ -67,6 +85,7 @@ export function detectLocaleFromStandards(projectPath) {
 
 export default {
   displayLanguageToLocale,
+  normalizeRequestedLocale,
   isLocalizedLocale,
   detectLocaleFromStandards,
   LOCALE_MAP

package/src/utils/skill-hash-ownership.js

@@ -0,0 +1,64 @@
+/**
+ * Which `manifest.skillHashes` records really describe files UDS installed.
+ *
+ * A record is `<agent>/<level>/<skill>/<file>`. It is UDS's only if `<skill>` is a skill UDS ships.
+ * Anything else got there because an older installer hashed the whole skills folder (XSPEC-454 R2):
+ * the adopter's own skills, the `agents/` / `workflows/` / `_shared/` folders an old CLI copied in by
+ * mistake (which a later `uds update` deletes — leaving the record behind), and UDS's own
+ * `.manifest.json` bookkeeping file. None of those are skills UDS can vouch for, so none of them may
+ * decide whether `uds check` says the project is compliant.
+ *
+ * @module utils/skill-hash-ownership
+ */
+
+import { getAvailableSkillNames } from './skills-installer.js';
+
+/**
+ * Below this many shipped skills the source tree did not load; it does not mean UDS stopped shipping
+ * skills. Without this guard a broken install would classify every record as foreign and empty the
+ * manifest (same guard as pruneRetiredHashes' registry-size check).
+ */
+const MIN_SHIPPED_SKILLS = 10;
+
+/**
+ * @param {string} key - A skillHashes key
+ * @param {Set<string>} shipped - Names of the skills UDS ships
+ * @returns {boolean}
+ */
+export function isUdsSkillHashKey(key, shipped) {
+  const parts = String(key).split('/');
+  // agent / level / skill / at least one file path segment
+  return parts.length >= 4 && shipped.has(parts[2]);
+}
+
+/**
+ * Drop the skillHashes records that do not describe a file UDS installed. Mutates `manifest`.
+ *
+ * @param {Object} manifest - Project manifest
+ * @param {Set<string>} [shipped] - Injection point for tests; defaults to the skills this CLI ships
+ * @returns {string[]} The keys that were dropped, sorted
+ */
+export function pruneForeignSkillHashes(manifest, shipped = new Set(getAvailableSkillNames())) {
+  const hashes = manifest?.skillHashes;
+  if (!hashes || shipped.size < MIN_SHIPPED_SKILLS) return [];
+  const dropped = [];
+  for (const key of Object.keys(hashes)) {
+    if (isUdsSkillHashKey(key, shipped)) continue;
+    delete hashes[key];
+    dropped.push(key);
+  }
+  return dropped.sort();
+}
+
+/**
+ * Which skill files `uds check` has to report: the missing and the changed ones, as one list.
+ *
+ * Its result is what the verdict is built from. `uds check` used to throw the integrity result away, so a
+ * deleted skill file printed a red ✗ and the run still ended "compliant", exit 0 (XSPEC-454 R2).
+ *
+ * @param {{ missing?: string[], modified?: string[] }} status - Result of the Skills integrity check
+ * @returns {string[]}
+ */
+export function skillIssuesOf(status) {
+  return [...(status?.missing || []), ...(status?.modified || [])];
+}

package/src/utils/skills-installer.js

@@ -248,8 +248,19 @@ export async function installSkillsForAgent(agent, level, skillNames = null, pro
 
     // Compute file hashes for tracking
     // Key format: agent/level/skillName/filename (e.g., "opencode/project/commit-standards/SKILL.md")
+    //
+    // XSPEC-454 R2: only the skills THIS run installed are recorded. This used to hash the whole
+    // target directory, so everything that happened to sit in `.claude/skills/` — the adopter's own
+    // skills, and the `agents/`, `workflows/`, `_shared/` folders an old CLI copied in by mistake —
+    // became "files UDS installed". `uds update` later (rightly) deleted the old strays but kept their
+    // records, and `uds check` listed 26 of them as missing. A record has to mean "UDS wrote this".
+    // `.manifest.json` is deliberately not recorded either: it is UDS's own bookkeeping, rewritten by
+    // every install, and nothing a user edits — a hash of it could only ever raise a false alarm.
     const baseKey = `${agent}/${level}`;
-    results.fileHashes = computeDirectoryHashes(targetDir, baseKey);
+    results.fileHashes = {};
+    for (const name of results.installed) {
+      Object.assign(results.fileHashes, computeDirectoryHashes(join(targetDir, name), `${baseKey}/${name}`));
+    }
   }
 
   return results;

package/src/utils/test-change-check.js

@@ -0,0 +1,160 @@
+/**
+ * "This commit changes code and touches no test" — the pre-commit check.
+ * // implements XSPEC-444 R2
+ *
+ * Runs inside `uds check`, which is what the pre-commit hook UDS writes calls. It reads
+ * what is staged (`git diff --cached`); with nothing staged (a CI run, a manual
+ * `uds check`) it says nothing, because there is no commit to judge.
+ *
+ * What it decides, per staged file (see test-policy.js for the table):
+ *   source + no test in the same change   → warn, listing every code file
+ *   a file of a type the table has never seen → warn, listing it and saying how to
+ *                                           classify it. Never read as "fine".
+ *   pure rename (git's R100)              → exempt; recorded in the output with its reason
+ *   deletion                              → not a code change that needs a test
+ *   `exempt` entry in the policy          → exempt; recorded with the adopter's reason
+ *
+ * Severity: "warn" by default. `"mode": "block"` in `.standards/test-policy.json` makes a
+ * code change without a test fail the check. An unclassified file never blocks — it is
+ * UDS's own gap, not the committer's.
+ *
+ * NOT done here, on purpose (reported to the maintainer instead of guessed):
+ *   - the ratchet ("count of unpaired changes may only go down"): `uds check` is read-only
+ *     by design and the spec does not say where the baseline lives or what a "change" is
+ *     counted in.
+ *   - per-commit exemption with a reason: a pre-commit hook cannot read the commit message
+ *     (that is the commit-msg hook), so a per-commit reason has nowhere to be read from.
+ *     Standing exemptions with reasons are `exempt` entries in the policy file.
+ */
+
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import { loadPolicy, classifyPath, POLICY_FILE } from './test-policy.js';
+
+/**
+ * Parse `git diff --name-status -z` output.
+ * Records: `A\0path\0`, `M\0path\0`, `D\0path\0`, `R100\0old\0new\0`, `C75\0old\0new\0`.
+ * @returns {{ status: string, path: string, oldPath?: string, similarity?: number }[]}
+ */
+export function parseNameStatusZ(output) {
+  const parts = output.split('\0');
+  if (parts[parts.length - 1] === '') parts.pop();
+  const out = [];
+  for (let i = 0; i < parts.length;) {
+    const code = parts[i++];
+    if (!code) continue;
+    const letter = code[0];
+    if (letter === 'R' || letter === 'C') {
+      out.push({ status: letter, oldPath: parts[i++], path: parts[i++], similarity: parseInt(code.slice(1), 10) || 0 });
+    } else {
+      out.push({ status: letter, path: parts[i++] });
+    }
+  }
+  return out;
+}
+
+/** The staged changes of the repository at `projectPath`, or `{ error }` when git cannot say. */
+export function readStagedChanges(projectPath) {
+  try {
+    const out = execFileSync('git', ['-c', 'core.quotepath=off', 'diff', '--cached', '--name-status', '-M', '-z'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 64 * 1024 * 1024
+    });
+    return { changes: parseNameStatusZ(out) };
+  } catch (e) {
+    const stderr = String(e.stderr || e.message || '').trim().split('\n')[0];
+    // "not a git repository" is not a failure of this check: there is no commit to judge.
+    if (/not a git repository/i.test(stderr) || e.code === 'ENOENT') return { notRepo: true, error: stderr || 'git not found' };
+    return { error: stderr || 'git diff failed' };
+  }
+}
+
+/**
+ * Judge a list of staged changes against a policy. Pure: no I/O.
+ * @returns {{
+ *   staged: number, source: string[], tests: string[], unclassified: string[],
+ *   exempt: {path:string, reason:string}[], verdict: 'none'|'ok'|'warn'
+ * }}
+ */
+export function judgeChanges(changes, policy) {
+  const result = { staged: changes.length, source: [], tests: [], unclassified: [], exempt: [], verdict: 'none' };
+  for (const ch of changes) {
+    if (ch.status === 'D') continue;
+    const cls = classifyPath(ch.path, policy);
+    if (cls.kind === 'test') { result.tests.push(ch.path); continue; }
+    if (cls.kind === 'unclassified') { result.unclassified.push(ch.path); continue; }
+    if (cls.kind !== 'source') continue; // ignored / noncode
+    if (ch.status === 'R' && ch.similarity === 100) {
+      result.exempt.push({ path: ch.path, reason: `pure rename of ${ch.oldPath} (content unchanged)` });
+      continue;
+    }
+    if (cls.exempt) {
+      result.exempt.push({ path: ch.path, reason: `policy exemption "${cls.exempt.pattern}": ${cls.exempt.reason}` });
+      continue;
+    }
+    result.source.push(ch.path);
+  }
+  if (result.staged === 0) result.verdict = 'none';
+  else if (result.source.length > 0 && result.tests.length === 0) result.verdict = 'warn';
+  else result.verdict = 'ok';
+  return result;
+}
+
+const show = (list, max = 12) => {
+  const lines = list.slice(0, max).map((f) => `      - ${f}`);
+  if (list.length > max) lines.push(`      ... and ${list.length - max} more`);
+  return lines;
+};
+
+/**
+ * Run the check and print its report. Never throws; never changes the exit code in
+ * "warn" mode. In "block" mode a code change with no test sets `process.exitCode = 1`.
+ * @returns {{ ran: boolean, stagedCount: number, verdict: string, mode: string, blocked: boolean, policyProblems: string[] }}
+ */
+export function runTestChangeCheck(projectPath, { log = console.log } = {}) {
+  const { policy, problems } = loadPolicy(projectPath);
+  const staged = readStagedChanges(projectPath);
+  const base = { ran: false, stagedCount: 0, verdict: 'none', mode: policy.mode, blocked: false, policyProblems: problems };
+
+  for (const p of problems) log(chalk.yellow(`  ⚠ [test-change] ${p}`));
+
+  if (staged.notRepo) return base;
+  if (staged.error) {
+    log(chalk.yellow(`  ⚠ [test-change] could not read the staged changes (${staged.error}); the code-without-test check did not run.`));
+    return base;
+  }
+  const judged = judgeChanges(staged.changes, policy);
+  const result = { ...base, ran: true, stagedCount: judged.staged, verdict: judged.verdict };
+  if (judged.staged === 0) return result;
+
+  const blocking = judged.verdict === 'warn' && policy.mode === 'block';
+
+  if (judged.verdict === 'warn') {
+    const head = blocking
+      ? `  ✗ [test-change] BLOCKED: this commit changes ${judged.source.length} code file(s) and touches no test file (XSPEC-444 R2, mode "block").`
+      : `  ⚠ [test-change] This commit changes ${judged.source.length} code file(s) and touches no test file (XSPEC-444 R2). Warning only — the commit is not blocked.`;
+    log(blocking ? chalk.red(head) : chalk.yellow(head));
+    log(chalk.gray('    code files changed without a test change:'));
+    for (const l of show(judged.source)) log(chalk.gray(l));
+    log(chalk.gray('    A change to behavior needs a test that fails without it. Not a behavior change (generated code, a rename with edits)?'));
+    log(chalk.gray(`    Record the exemption with its reason in ${POLICY_FILE}:  "exempt": [{ "pattern": "<glob>", "reason": "<why>" }]`));
+    if (!blocking) log(chalk.gray(`    To make this block the commit instead: set "mode": "block" in ${POLICY_FILE}.`));
+  }
+  if (judged.unclassified.length > 0) {
+    log(chalk.yellow(`  ⚠ [test-change] ${judged.unclassified.length} changed file(s) are of a type UDS does not recognize, so it cannot tell whether they are code (never assumed fine, never blocks):`));
+    for (const l of show(judged.unclassified)) log(chalk.gray(l));
+    log(chalk.gray(`    Say what they are in ${POLICY_FILE}: "sourceExtensions": ["<ext>"] (code) or "nonCodeExtensions": ["<ext>"] (not code); test files: "testPatterns".`));
+  }
+  if (judged.exempt.length > 0) {
+    log(chalk.gray('  ℹ [test-change] exempt from the test requirement, with the reason on record:'));
+    for (const e of judged.exempt.slice(0, 12)) log(chalk.gray(`      - ${e.path} — ${e.reason}`));
+  }
+  if (blocking) {
+    process.exitCode = 1;
+    result.blocked = true;
+  }
+  if (judged.verdict === 'warn' || judged.unclassified.length > 0 || judged.exempt.length > 0) log();
+  return result;
+}

package/src/utils/test-policy.js

@@ -0,0 +1,214 @@
+/**
+ * Which files are code, which are tests, and which UDS cannot tell — one answer,
+ * configurable per project. // implements XSPEC-444 R2 (and the classification R5's scripts share)
+ *
+ * Why this is data and not a branch per language: UDS is a general standard, and the
+ * check built on this must work in every language an adopter writes. So "what is a test
+ * file" is a list of path patterns with defaults for the common ecosystems, and a project
+ * adds its own in `.standards/test-policy.json`. No test framework is named anywhere.
+ *
+ * Three answers beyond "code" and "test", and the third is the point:
+ *   - `noncode`      docs, data, config, images — known not to need a test
+ *   - `ignored`      generated/vendored/tooling paths (node_modules, dist, .github, ...)
+ *   - `unclassified` an extension this table has never heard of. It is NOT assumed to be
+ *                    code and it is NOT assumed to be safe: the caller must say so out
+ *                    loud. A language UDS does not know must not read as "passed".
+ *
+ * The same defaults are copied into the two gate scripts UDS ships to adopters
+ * (templates/gates/check-anti-fake-tests.mjs, check-stubs.mjs) because those run in a
+ * project with no UDS code beside them. A test (test-policy-drift) compares all three.
+ *
+ * Policy file `.standards/test-policy.json` (optional; every list ADDS to the defaults):
+ *   {
+ *     "mode": "warn" | "block",                 // default "warn"
+ *     "testDirs": ["integration"],               // directory names that hold tests
+ *     "testPatterns": ["*.itest.*"],             // file-name globs of test files
+ *     "sourceExtensions": ["zig"],               // extensions that are code
+ *     "nonCodeExtensions": ["gradle"],           // extensions that are not
+ *     "ignore": ["generated/**"],                // path globs to leave alone
+ *     "exempt": [{ "pattern": "src/gen/**", "reason": "generated by protoc" }]
+ *   }
+ * An `exempt` entry without a `reason` is not honored (and is reported): an exemption that
+ * leaves no explanation is just a switch.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+// ---- BEGIN SHARED POLICY (identical in templates/gates/check-anti-fake-tests.mjs and check-stubs.mjs; test-policy-drift.test.js compares them) ----
+/** Where an adopter's policy lives (inside `.standards/`, beside release-config.yaml). */
+export const POLICY_FILE = '.standards/test-policy.json';
+
+export const DEFAULT_POLICY = Object.freeze({
+  mode: 'warn',
+  testDirs: Object.freeze(['test', 'tests', '__tests__', 'spec', 'e2e']),
+  testPatterns: Object.freeze([
+    '*.test.*', '*.spec.*', '*_test.*', '*_spec.*', 'test_*.*', 'conftest.py',
+    '*Test.*', '*Tests.*', '*Spec.scala', '*Spec.kt', '*Spec.groovy'
+  ]),
+  sourceExtensions: Object.freeze([
+    'js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'mts', 'cts', 'vue', 'svelte', 'astro',
+    'py', 'pyi', 'java', 'kt', 'kts', 'scala', 'groovy', 'go', 'rs', 'rb', 'php', 'cs', 'fs', 'vb',
+    'swift', 'm', 'mm', 'dart', 'c', 'h', 'cc', 'cpp', 'cxx', 'hpp', 'hh',
+    'ex', 'exs', 'erl', 'hrl', 'lua', 'pl', 'pm', 'r', 'jl', 'clj', 'cljs', 'hs', 'ml', 'mli',
+    'sh', 'bash', 'zsh', 'ps1'
+  ]),
+  nonCodeExtensions: Object.freeze([
+    'md', 'mdx', 'txt', 'rst', 'adoc', 'json', 'jsonc', 'json5', 'yaml', 'yml', 'toml', 'ini', 'cfg',
+    'conf', 'properties', 'env', 'lock', 'xml', 'csv', 'tsv', 'svg', 'png', 'jpg', 'jpeg', 'gif', 'ico',
+    'webp', 'avif', 'pdf', 'woff', 'woff2', 'ttf', 'otf', 'eot', 'map', 'html', 'htm', 'css', 'scss',
+    'sass', 'less', 'sql', 'gitignore', 'gitattributes', 'editorconfig', 'npmrc', 'nvmrc', 'license',
+    'log', 'snap'
+  ]),
+  nonCodeNames: Object.freeze([
+    'LICENSE', 'README', 'CHANGELOG', 'NOTICE', 'AUTHORS', 'CODEOWNERS', 'Dockerfile', 'Makefile', 'Procfile'
+  ]),
+  ignoreDirs: Object.freeze([
+    'node_modules', 'vendor', 'dist', 'build', 'coverage', '.git', '.standards', '.claude', '.husky',
+    '.github', 'docs', 'target', '__pycache__', '.venv', 'venv', '.next', '.nuxt', '.idea', '.vscode',
+    '.ruff_cache', '.pytest_cache', '.mypy_cache', '.tox', '.gradle', '.cache', '.turbo', '.svelte-kit',
+    '.parcel-cache', '.terraform', '.dart_tool', '.eggs'
+  ]),
+  ignore: Object.freeze(['**/*.min.js', '**/*.min.css', '**/*.d.ts']),
+  exempt: Object.freeze([])
+});
+
+const norm = (p) => String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+
+/** Glob → RegExp. `*` stays inside a path segment, `**` crosses them, `?` is one non-slash character. */
+export function globToRegex(glob) {
+  const g = norm(glob);
+  let re = '';
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === '*') {
+      if (g[i + 1] === '*') {
+        if (g[i + 2] === '/') { re += '(?:.*/)?'; i += 2; } else { re += '.*'; i += 1; }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if ('\\^$+.()|{}[]'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** A glob with no slash is a file-name glob (matches the basename anywhere); otherwise it matches the whole path. */
+function matchesGlob(relPath, glob) {
+  const p = norm(relPath);
+  const g = norm(glob);
+  const target = g.includes('/') ? p : p.split('/').pop();
+  return globToRegex(g).test(target);
+}
+
+const extOf = (relPath) => {
+  const base = norm(relPath).split('/').pop();
+  const i = base.lastIndexOf('.');
+  return i > 0 ? base.slice(i + 1).toLowerCase() : '';
+};
+
+/**
+ * Read `.standards/test-policy.json` and merge it over the defaults.
+ * @returns {{ policy: object, problems: string[], source: string|null }}
+ *   `problems` is never swallowed: an unreadable file or a bad value is reported, and the
+ *   defaults (mode "warn") are what runs.
+ */
+export function loadPolicy(projectPath) {
+  const problems = [];
+  const policy = {
+    mode: DEFAULT_POLICY.mode,
+    testDirs: [...DEFAULT_POLICY.testDirs],
+    testPatterns: [...DEFAULT_POLICY.testPatterns],
+    sourceExtensions: [...DEFAULT_POLICY.sourceExtensions],
+    nonCodeExtensions: [...DEFAULT_POLICY.nonCodeExtensions],
+    nonCodeNames: [...DEFAULT_POLICY.nonCodeNames],
+    ignoreDirs: [...DEFAULT_POLICY.ignoreDirs],
+    ignore: [...DEFAULT_POLICY.ignore],
+    exempt: []
+  };
+  const file = join(projectPath, POLICY_FILE);
+  if (!existsSync(file)) return { policy, problems, source: null };
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf-8').replace(/^\uFEFF/, ''));
+  } catch (e) {
+    problems.push(`${POLICY_FILE} cannot be read (${e.message}); defaults are in effect`);
+    return { policy, problems, source: POLICY_FILE };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    problems.push(`${POLICY_FILE} must be a JSON object; defaults are in effect`);
+    return { policy, problems, source: POLICY_FILE };
+  }
+
+  if (raw.mode !== undefined) {
+    if (raw.mode === 'warn' || raw.mode === 'block') policy.mode = raw.mode;
+    else problems.push(`${POLICY_FILE}: "mode" must be "warn" or "block", got ${JSON.stringify(raw.mode)}; "warn" is in effect`);
+  }
+  for (const key of ['testDirs', 'testPatterns', 'sourceExtensions', 'nonCodeExtensions', 'ignore']) {
+    if (raw[key] === undefined) continue;
+    if (!Array.isArray(raw[key]) || raw[key].some((v) => typeof v !== 'string' || !v)) {
+      problems.push(`${POLICY_FILE}: "${key}" must be an array of non-empty strings; it is ignored`);
+      continue;
+    }
+    const add = key === 'sourceExtensions' || key === 'nonCodeExtensions'
+      ? raw[key].map((v) => v.replace(/^\./, '').toLowerCase())
+      : raw[key];
+    policy[key] = [...policy[key], ...add];
+  }
+  if (raw.exempt !== undefined) {
+    if (!Array.isArray(raw.exempt)) {
+      problems.push(`${POLICY_FILE}: "exempt" must be an array; it is ignored`);
+    } else {
+      raw.exempt.forEach((e, i) => {
+        const okPattern = e && typeof e.pattern === 'string' && e.pattern.trim();
+        const okReason = e && typeof e.reason === 'string' && e.reason.trim();
+        if (!okPattern) problems.push(`${POLICY_FILE}: exempt[${i}] has no "pattern"; it is ignored`);
+        else if (!okReason) problems.push(`${POLICY_FILE}: exempt[${i}] ("${e.pattern}") has no "reason" and is NOT honored — an exemption must say why`);
+        else policy.exempt.push({ pattern: e.pattern, reason: e.reason.trim() });
+      });
+    }
+  }
+  return { policy, problems, source: POLICY_FILE };
+}
+
+/**
+ * Classify one project-relative path.
+ * @returns {{ kind: 'ignored'|'noncode'|'test'|'source'|'unclassified', ext: string, exempt?: {pattern:string, reason:string} }}
+ */
+export function classifyPath(relPath, policy = DEFAULT_POLICY) {
+  const p = norm(relPath);
+  const segments = p.split('/');
+  const base = segments[segments.length - 1];
+  const dirs = segments.slice(0, -1);
+  const ext = extOf(p);
+  const sets = {
+    source: new Set(policy.sourceExtensions || DEFAULT_POLICY.sourceExtensions),
+    noncode: new Set(policy.nonCodeExtensions || DEFAULT_POLICY.nonCodeExtensions),
+    names: new Set(policy.nonCodeNames || DEFAULT_POLICY.nonCodeNames),
+    ignoreDirs: new Set(policy.ignoreDirs || DEFAULT_POLICY.ignoreDirs)
+  };
+
+  if (dirs.some((d) => sets.ignoreDirs.has(d))) return { kind: 'ignored', ext };
+  if ((policy.ignore || DEFAULT_POLICY.ignore).some((g) => matchesGlob(p, g))) return { kind: 'ignored', ext };
+
+  const docsLike = sets.noncode.has(ext) || sets.names.has(base) || sets.names.has(base.replace(/\.[^.]*$/, ''));
+  const inTestDir = dirs.some((d) => (policy.testDirs || DEFAULT_POLICY.testDirs).includes(d));
+  const testNamed = (policy.testPatterns || DEFAULT_POLICY.testPatterns).some((g) => matchesGlob(p, g));
+
+  // A test is a test even when its data is JSON; but a README inside tests/ is documentation.
+  if ((inTestDir || testNamed) && !['md', 'mdx', 'txt', 'rst', 'adoc'].includes(ext)) return { kind: 'test', ext };
+  // Dot-files (.prettierrc, .eslintrc.js, .env.local ...) are tool configuration, not product code.
+  if (docsLike || base.startsWith('.')) return { kind: 'noncode', ext };
+  if (sets.source.has(ext)) {
+    const exempt = (policy.exempt || []).find((e) => matchesGlob(p, e.pattern));
+    return exempt ? { kind: 'source', ext, exempt } : { kind: 'source', ext };
+  }
+  return { kind: 'unclassified', ext };
+}
+// ---- END SHARED POLICY ----

package/src/utils/update-summary.js

@@ -0,0 +1,29 @@
+/**
+ * One-line summaries `uds update` prints, kept apart from the command so what they say can be tested
+ * without running an update.
+ *
+ * @module utils/update-summary
+ */
+
+const agentOf = (inst) => (typeof inst === 'string' ? inst : inst.agent);
+
+/**
+ * "Updated N commands for M AI tools: <where>" (XSPEC-454 R4).
+ *
+ * The number of tools and the number of commands are different numbers and are filled into different
+ * slots. The summary used to reuse `commandsUpdated`, a message worded "N AI tools" in every language,
+ * and feed it the command-file count: one OpenCode install printed "Updated Commands for 51 AI tools".
+ *
+ * @param {Object} msg - `t().commands.update`
+ * @param {Array<string|{agent: string}>} installations - The targets the commands went to
+ * @param {{ totalInstalled: number }} result - The installer's result
+ * @param {string} locations - Already-formatted list of where they went
+ * @returns {string}
+ */
+export function commandsUpdatedMessage(msg, installations, result, locations) {
+  const tools = new Set((installations || []).map(agentOf)).size;
+  return (msg.commandsUpdatedCounts || 'Updated {commands} commands for {tools} AI tool(s): {locations}')
+    .replace('{tools}', tools)
+    .replace('{commands}', result.totalInstalled)
+    .replace('{locations}', locations);
+}

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.14.0-beta.3",
+  "version": "6.14.0-beta.5",
   "lastUpdated": "2026-05-13",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "6.14.0-beta.3"
+      "version": "6.14.0-beta.5"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "6.14.0-beta.3",
+      "version": "6.14.0-beta.5",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -382,6 +382,10 @@
       "skills/brainstorm-assistant/SKILL.md",
       "skills/brainstorm-assistant/guide.md"
     ],
+    "comprehension-ladder": [
+      "skills/comprehension-ladder/SKILL.md",
+      "skills/comprehension-ladder/eval-cases.md"
+    ],
     "bdd-assistant": [
       "skills/bdd-assistant/SKILL.md",
       "skills/bdd-assistant/guide.md",
@@ -1536,6 +1540,16 @@
       "description": "Traditional Chinese (Taiwan) localization for all standards",
       "applicability": "Traditional Chinese speaking teams"
     },
+    {
+      "id": "zh-cn-locale",
+      "name": "Simplified Chinese Locale",
+      "nameZh": "简体中文本地化",
+      "source": "extensions/locales/zh-cn.md",
+      "category": "extension",
+      "skillName": null,
+      "description": "Simplified Chinese (Mainland China) localization for all standards",
+      "applicability": "Simplified Chinese speaking teams"
+    },
     {
       "id": "copilot-integration",
       "name": "GitHub Copilot Instructions",
@@ -2295,7 +2309,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.14.0-beta.3",
+      "version": "6.14.0-beta.5",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2307,7 +2321,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.14.0-beta.3",
+      "version": "6.14.0-beta.5",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2319,7 +2333,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.14.0-beta.3",
+      "version": "6.14.0-beta.5",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2331,7 +2345,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.14.0-beta.3",
+      "version": "6.14.0-beta.5",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"