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

package/src/reconciler/index.js

@@ -28,6 +28,8 @@ import { scanActualState, legacyDiscovery } from './actual-state-scanner.js';
 import { computeDiff, createEmptyPlan } from './diff-engine.js';
 import { executePlan } from './plan-executor.js';
 import { rollback } from './backup-manager.js';
+import { pruneForeignSkillHashes } from '../utils/skill-hash-ownership.js';
+import { pruneForeignCommandHashes } from '../utils/command-hash-ownership.js';
 
 /**
  * Full reconciliation pipeline.
@@ -72,11 +74,23 @@ function reconcileFileHashes(manifest, verifiedPristine) {
     (k) => k.startsWith('.claude/skills/') || k.startsWith('.claude/commands/')
   );
 
-  if (!verifiedPristine?.length && stale.length === 0) return null;
+  // XSPEC-454 R2 step 1: forget skillHashes records that were never UDS's (see
+  // utils/skill-hash-ownership.js). They are not harmless: once `uds check` counts a missing
+  // skill file against the verdict, a record for a folder an older update already removed
+  // would fail the project for a file nobody can restore. This runs on every apply, plan empty
+  // or not, so an existing project is corrected by its next `uds update --apply` with nothing
+  // for the adopter to do.
+  const skillProbe = { skillHashes: { ...(manifest.skillHashes || {}) } };
+  const foreignSkillKeys = pruneForeignSkillHashes(skillProbe);
+  // ...and the same for command records that name a command UDS does not ship.
+  const commandProbe = { commandHashes: { ...(manifest.commandHashes || {}) } };
+  const foreignCommandKeys = pruneForeignCommandHashes(commandProbe);
+
+  if (!verifiedPristine?.length && stale.length === 0 && foreignSkillKeys.length === 0 && foreignCommandKeys.length === 0) return null;
 
   const kept = Object.fromEntries(Object.entries(current).filter(([k]) => !stale.includes(k)));
   const corrected = {};
-  let count = stale.length;
+  let count = stale.length + foreignSkillKeys.length + foreignCommandKeys.length;
 
   for (const entry of verifiedPristine || []) {
     const key = entry.path.replace(/\\/g, '/');
@@ -92,7 +106,12 @@ function reconcileFileHashes(manifest, verifiedPristine) {
 
   if (count === 0) return null;
   return {
-    manifest: { ...manifest, fileHashes: { ...kept, ...corrected } },
+    manifest: {
+      ...manifest,
+      fileHashes: { ...kept, ...corrected },
+      ...(foreignSkillKeys.length > 0 ? { skillHashes: skillProbe.skillHashes } : {}),
+      ...(foreignCommandKeys.length > 0 ? { commandHashes: commandProbe.commandHashes } : {})
+    },
     count
   };
 }
@@ -133,7 +152,10 @@ export async function reconcile(projectPath, options = {}) {
   // own binding rather than reassigning it.
   const hashFix = reconcileFileHashes(manifest, reconciliationPlan.verifiedPristine);
   const effectiveManifest = hashFix ? hashFix.manifest : manifest;
-  if (hashFix) writeManifest(effectiveManifest, projectPath);
+  // With a non-empty plan the executor writes `effectiveManifest` itself, AFTER it has taken its backup.
+  // Writing it here first would put the hash correction into the backup's "before" copy, so a rollback
+  // could not give back the manifest byte for byte (XSPEC-454 R1).
+  if (hashFix && reconciliationPlan.actions.length === 0) writeManifest(effectiveManifest, projectPath);
 
   // Step 5: Execute plan
   if (reconciliationPlan.actions.length === 0) {
@@ -242,5 +264,5 @@ async function getManifest(projectPath) {
 
 // Re-export for convenience
 export { formatPlan } from './diff-engine.js';
-export { listBackups } from './backup-manager.js';
+export { listBackups, createStepBackup, finalizeBackup, cleanupBackups } from './backup-manager.js';
 export { migrateAndBackfill } from './manifest-migrator.js';

package/src/reconciler/install-roots.js

@@ -0,0 +1,90 @@
+/**
+ * Where `uds update` writes Skills and Commands, in the terms a backup needs (XSPEC-454 R1):
+ * project-relative directories it can copy, and targets outside the project it cannot.
+ *
+ * A user-level target (`~/.claude/skills`) is shared by every project on the machine. Copying it into
+ * one project's backup, and writing it back on that project's rollback, would undo other projects'
+ * updates — so it is listed as "not backed up" and the rollback says so, rather than touching it.
+ *
+ * @module reconciler/install-roots
+ */
+
+import { relative, isAbsolute } from 'path';
+import { getSkillsDirForAgent, getCommandsDirForAgent } from '../config/ai-agent-paths.js';
+import { getAvailableSkillNames, getAvailableCommandNames } from '../utils/skills-installer.js';
+
+const normalizeInstallation = (inst) =>
+  typeof inst === 'string' ? { agent: inst, level: 'project' } : { agent: inst.agent, level: inst.level || 'project' };
+
+/** Project-relative posix path when `abs` is inside the project, else null. */
+function insideProject(projectPath, abs) {
+  if (!abs) return null;
+  const rel = relative(projectPath, abs).replace(/\\/g, '/');
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null;
+  return rel;
+}
+
+/**
+ * @param {string} projectPath
+ * @param {Array<string|{agent: string, level?: string}>} installations
+ * @param {'skills'|'commands'} kind
+ * @returns {{ dirs: string[], outside: Array<{path: string, reason: string}> }}
+ */
+export function installRoots(projectPath, installations, kind) {
+  const dirs = [];
+  const outside = [];
+  for (const raw of installations || []) {
+    const { agent, level } = normalizeInstallation(raw);
+    if (level === 'marketplace') continue; // nothing on disk
+    const abs = kind === 'skills'
+      ? getSkillsDirForAgent(agent, level, projectPath)
+      : getCommandsDirForAgent(agent, level, projectPath);
+    if (!abs) continue;
+    const rel = insideProject(projectPath, abs);
+    if (rel) {
+      dirs.push(rel);
+    } else {
+      outside.push({
+        path: abs,
+        reason: `${kind} installed at user level for ${agent}; shared by every project on this machine, so it is not backed up and not rolled back`
+      });
+    }
+  }
+  return { dirs: [...new Set(dirs)], outside };
+}
+
+/**
+ * The bookkeeping file every Skills/Commands install rewrites, for each project-level target.
+ * A reconciler plan names skill and command files, never these, yet they change on every run.
+ */
+export function bookkeepingFiles(projectPath, manifest, { skills, commands }) {
+  const out = [];
+  if (skills) out.push(...installRoots(projectPath, manifest?.skills?.installations, 'skills').dirs.map((d) => `${d}/.manifest.json`));
+  if (commands) out.push(...installRoots(projectPath, manifest?.commands?.installations, 'commands').dirs.map((d) => `${d}/.manifest.json`));
+  return out;
+}
+
+/**
+ * What a `--skills` / `--commands` step is going to write, as paths a backup can copy: the skill folders
+ * (or command files) UDS ships, and the bookkeeping file, inside each project-level target.
+ *
+ * Deliberately not the whole target folder. That folder also holds the adopter's own skills and commands;
+ * a backup that copied them would let a rollback write them back — undoing an edit the adopter made
+ * after the update, to a file UDS never touched. A shipped name that is not on disk yet is still listed:
+ * the backup records it as absent, which is what lets a rollback remove it again.
+ *
+ * @param {string} projectPath
+ * @param {Array<string|{agent: string, level?: string}>} installations
+ * @param {'skills'|'commands'} kind
+ * @returns {{ paths: string[], outside: Array<{path: string, reason: string}> }}
+ */
+export function stepWritePaths(projectPath, installations, kind) {
+  const { dirs, outside } = installRoots(projectPath, installations, kind);
+  const names = kind === 'skills' ? getAvailableSkillNames() : getAvailableCommandNames();
+  const paths = [];
+  for (const dir of dirs) {
+    paths.push(`${dir}/.manifest.json`);
+    for (const name of names) paths.push(kind === 'skills' ? `${dir}/${name}` : `${dir}/${name}.md`);
+  }
+  return { paths, outside };
+}

package/src/reconciler/plan-executor.js

@@ -28,7 +28,8 @@ import { writeManifest } from '../core/manifest.js';
 import { getRepositoryInfo } from '../utils/registry.js';
 import { displayLanguageToLocale } from '../utils/locale.js';
 import { computeFileHash, pruneIntegrationFileHashes } from '../utils/hasher.js';
-import { createBackup, cleanupBackups } from './backup-manager.js';
+import { createBackup, cleanupBackups, finalizeBackup } from './backup-manager.js';
+import { bookkeepingFiles } from './install-roots.js';
 
 /**
  * @typedef {Object} ExecutionResult
@@ -75,7 +76,13 @@ export async function executePlan(projectPath, plan, manifest, options = {}) {
 
   // Create backup
   if (backup && !dryRun) {
-    const backupResult = createBackup(projectPath, plan);
+    // XSPEC-454 R1: the Skills and Commands installers also rewrite `.manifest.json` in each target
+    // folder. No plan action names it, so it has to be watched explicitly or a rollback leaves the new one.
+    const bookkeeping = bookkeepingFiles(projectPath, manifest, {
+      skills: plan.actions.some((a) => a.category === 'skill'),
+      commands: plan.actions.some((a) => a.category === 'command')
+    });
+    const backupResult = createBackup(projectPath, plan, { alsoWatch: bookkeeping });
     // Abort if ANY planned path could not be backed up — not only if every one
     // failed.
     //
@@ -197,6 +204,10 @@ export async function executePlan(projectPath, plan, manifest, options = {}) {
         error: `Failed to write manifest: ${err.message}`
       });
     }
+    // XSPEC-454 R1: now that the step is over — whether or not that last write worked — record what it
+    // created and what the manifest became. This has to stay after the manifest write: the chain between
+    // consecutive backups is "the manifest this step left == the manifest the next step started from".
+    finalizeBackup(projectPath, backupId);
   }
 
   const summary = {
@@ -422,6 +433,16 @@ async function executeSkillBatch(projectPath, skillActions, manifest) {
       if (existsSync(targetPath)) {
         rmSync(targetPath, { recursive: true, force: true });
       }
+      // XSPEC-454 R2: a deleted skill folder must also lose its hash records. Commands already
+      // do this (see executeCommandBatch); skills did not, so each folder removed here stayed in
+      // `skillHashes` and `uds check` later called every file in it missing — 26 of them for one project.
+      const meta = action.details?.metadata;
+      if (meta?.agent && meta?.level && meta?.skillName && manifest.skillHashes) {
+        const prefix = `${meta.agent}/${meta.level}/${meta.skillName}/`;
+        for (const key of Object.keys(manifest.skillHashes)) {
+          if (key.startsWith(prefix)) delete manifest.skillHashes[key];
+        }
+      }
       results.push({ action, success: true });
     } catch (err) {
       results.push({ action, success: false, error: err.message });

package/src/uninstallers/hook-uninstaller.js

@@ -303,7 +303,8 @@ export function uninstallHookScripts(projectPath, manifest, { dryRun = false, bl
   const result = { removed: [], skipped: [], errors: [], deletedPaths: [] };
   const files = manifest?.[RECORDS_KEY]?.files || {};
   const recorded = Object.entries(files)
-    .filter(([, rec]) => rec && rec.kind === RECORD_KINDS.HOOK_SCRIPT)
+    // gate-script: the scanners `uds init` writes to scripts/ (XSPEC-444 R5) — same proof rule as a hook script
+    .filter(([, rec]) => rec && (rec.kind === RECORD_KINDS.HOOK_SCRIPT || rec.kind === RECORD_KINDS.GATE_SCRIPT))
     .map(([rel]) => rel)
     .sort();
 

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

@@ -0,0 +1,103 @@
+/**
+ * Which `manifest.commandHashes` records `uds check` may hold this project to (XSPEC-454 R2, the
+ * Commands half).
+ *
+ * A record is `<agent>/<file>` (`opencode/commit.md`, `gemini-cli/commit.toml`) with no level in it.
+ * Two kinds of record do not describe a file this project's check can vouch for:
+ *
+ *   - FOREIGN: the name is not a command UDS ships (any more). A retired command whose file is gone is
+ *     a "missing" nobody can restore. These are dropped for good by `uds update`.
+ *   - ELSEWHERE: the command was installed at user level (`~/.config/opencode/command`), shared by every
+ *     project on the machine. The check looks inside the project, so every one of them would read
+ *     "missing" — and another project's `uds update` can rewrite them at any time, so "modified" would
+ *     be noise too. They are ignored by the check and left in the manifest (user-level update still
+ *     refreshes them).
+ *
+ * Both exist for the same reason the skills ones do: once a missing or changed command file counts toward
+ * the verdict, a record that points at nothing this project owns would fail the project for a file
+ * nobody can fix.
+ *
+ * @module utils/command-hash-ownership
+ */
+
+import { getAvailableCommandNames } from './skills-installer.js';
+import { getCommandFileExtension } from '../config/ai-agent-paths.js';
+
+/** Below this many shipped commands the source tree did not load; never treat that as "UDS ships none". */
+const MIN_SHIPPED_COMMANDS = 10;
+
+/**
+ * @param {string} key - A commandHashes key
+ * @param {Set<string>} shipped - Names of the commands UDS ships (no extension)
+ * @returns {boolean}
+ */
+export function isUdsCommandHashKey(key, shipped) {
+  const parts = String(key).split('/');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return false;
+  const [agent, file] = parts;
+  const ext = getCommandFileExtension(agent);
+  return file.endsWith(ext) && shipped.has(file.slice(0, -ext.length));
+}
+
+/**
+ * Drop the commandHashes records for commands UDS does not ship. Mutates `manifest`.
+ * @param {Object} manifest
+ * @param {Set<string>} [shipped] - Injection point for tests
+ * @returns {string[]} The keys dropped, sorted
+ */
+export function pruneForeignCommandHashes(manifest, shipped = new Set(getAvailableCommandNames())) {
+  const hashes = manifest?.commandHashes;
+  if (!hashes || shipped.size < MIN_SHIPPED_COMMANDS) return [];
+  const dropped = [];
+  for (const key of Object.keys(hashes)) {
+    if (isUdsCommandHashKey(key, shipped)) continue;
+    delete hashes[key];
+    dropped.push(key);
+  }
+  return dropped.sort();
+}
+
+/**
+ * Agents whose commands are installed, but only outside this project (user level or marketplace).
+ * An agent with no recorded installation at all is a legacy manifest and counts as project-level.
+ * @param {Object} manifest
+ * @returns {Set<string>}
+ */
+export function agentsWithCommandsOutsideProject(manifest) {
+  const levels = new Map(); // agent -> Set of levels
+  for (const entry of manifest?.commands?.installations || []) {
+    const agent = typeof entry === 'string' ? entry : entry?.agent;
+    const level = typeof entry === 'string' ? 'project' : (entry?.level || 'project');
+    if (!agent) continue;
+    if (!levels.has(agent)) levels.set(agent, new Set());
+    levels.get(agent).add(level);
+  }
+  return new Set([...levels].filter(([, set]) => !set.has('project')).map(([agent]) => agent));
+}
+
+/**
+ * The part of `manifest.commandHashes` this project's check is responsible for.
+ * @param {Object} manifest
+ * @returns {{ hashes: Object, ignored: string[] }} `ignored` are the keys set aside as ELSEWHERE
+ */
+export function projectCommandHashes(manifest) {
+  const all = manifest?.commandHashes || {};
+  const outside = agentsWithCommandsOutsideProject(manifest);
+  const hashes = {};
+  const ignored = [];
+  for (const [key, info] of Object.entries(all)) {
+    if (outside.has(key.split('/')[0])) ignored.push(key);
+    else hashes[key] = info;
+  }
+  return { hashes, ignored };
+}
+
+/**
+ * The command files `uds check` has to report: missing and modified, as one list. Its result is what the
+ * verdict is built from — it used to be discarded, like the Skills one.
+ * @param {{ missing?: string[], modified?: string[] }} status
+ * @returns {string[]}
+ */
+export function commandIssuesOf(status) {
+  return [...(status?.missing || []), ...(status?.modified || [])];
+}

package/src/utils/copier.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, copyFileSync } from 'fs';
+import { existsSync, mkdirSync, copyFileSync, readFileSync } from 'fs';
 import { dirname, join, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { downloadStandard, downloadIntegration } from './github.js';
@@ -78,6 +78,26 @@ export async function copyExtension(sourcePath, targetDir, projectPath) {
   }
 }
 
+/**
+ * Read the original of a source path from the installed package — never from the network.
+ *
+ * This is what `uds check --diff` compares an adopter's file against (XSPEC-453 R1). The original
+ * used to be downloaded from GitHub `main`: offline it failed, and whatever UDS had changed on `main`
+ * since the adopter installed was listed as a difference the adopter had made. The package's own copy
+ * is the version that was installed, so a difference against it is the adopter's.
+ *
+ * Returns `null` when the installed package has no such file; the caller says so by name. There is
+ * deliberately no fallback to a download here.
+ *
+ * @param {string} sourcePath - Relative path from repo root (e.g., 'ai/standards/x.ai.yaml', 'extensions/locales/zh-tw.md')
+ * @returns {string|null} File content, or null if the installed package does not contain it
+ */
+export function readPackagedSource(sourcePath) {
+  const source = getSourcePath(sourcePath);
+  if (!source) return null;
+  return readFileSync(source, 'utf-8');
+}
+
 /**
  * Copy a standard file to target project
  * Falls back to downloading from GitHub if local file not found

package/src/utils/gate-scripts.js

@@ -0,0 +1,141 @@
+/**
+ * The two scanners UDS ships into an adopter's project, and the code that runs them.
+ * // implements XSPEC-444 R5
+ *
+ * `full-coverage-testing` has always told adopters to "add scripts/check-stubs.sh and
+ * scripts/check-anti-fake-tests.sh", and its validator checked that those files EXIST —
+ * but UDS shipped neither, so the instruction could not be followed and the check could
+ * only ever say "missing". This is the missing half:
+ *
+ *   installGateScripts()   `uds init` writes the two scanners (templates/gates/*.mjs) to
+ *                          `<project>/scripts/`, records them for `uds uninstall`, and never
+ *                          overwrites a file that is already there.
+ *   runTestQualityGates()  `uds check` (what the pre-commit hook runs) executes the ones that
+ *                          are installed and prints what they found as a WARNING. It does not
+ *                          change the exit code unless the adopter set `"mode": "block"`.
+ *
+ * Why the scanners are written into the project instead of run from the CLI: they are the
+ * adopter's to read, edit and wire into CI (`node scripts/check-stubs.mjs` is a hard gate on
+ * its own), and a standard that says "this file must exist" is only honest if the file does.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { spawnSync } from 'child_process';
+import chalk from 'chalk';
+import { getRepoRoot } from './copier.js';
+import { newRecorder, mkdirTracked, recordFile, RECORD_KINDS } from '../core/install-records.js';
+import { loadPolicy } from './test-policy.js';
+import { readStagedChanges } from './test-change-check.js';
+
+/** The standard that asks for these scripts; they are only written when it is installed. */
+export const GATE_STANDARD_FILE = 'full-coverage-testing.ai.yaml';
+
+export const GATE_SCRIPTS = Object.freeze([
+  { file: 'check-anti-fake-tests.mjs', label: 'anti-fake-test', what: 'tests that cannot fail' },
+  { file: 'check-stubs.mjs', label: 'stub', what: 'placeholders and empty shells' }
+]);
+
+const templatePath = (file) => join(getRepoRoot(), 'templates', 'gates', file);
+const destRel = (file) => `scripts/${file}`;
+
+export function gateStandardInstalled(projectPath) {
+  return existsSync(join(projectPath, '.standards', GATE_STANDARD_FILE));
+}
+
+/**
+ * Write the scanners into `<project>/scripts/`. Never overwrites: a file that exists is the
+ * adopter's (they may have edited it), and is reported as kept.
+ * @param {string} projectPath
+ * @param {object} recorder   an install-records recorder (see core/install-records.js)
+ * @returns {{ written: string[], kept: string[], missingTemplate: string[], skipped?: string }}
+ */
+export function installGateScripts(projectPath, recorder = newRecorder()) {
+  const result = { written: [], kept: [], missingTemplate: [] };
+  if (!gateStandardInstalled(projectPath)) {
+    result.skipped = `${GATE_STANDARD_FILE} is not installed in this project`;
+    return result;
+  }
+  for (const { file } of GATE_SCRIPTS) {
+    const rel = destRel(file);
+    const dest = join(projectPath, rel);
+    if (existsSync(dest)) { result.kept.push(rel); continue; }
+    const src = templatePath(file);
+    if (!existsSync(src)) { result.missingTemplate.push(file); continue; }
+    mkdirTracked(recorder, projectPath, dirname(dest));
+    writeFileSync(dest, readFileSync(src, 'utf-8'), 'utf-8');
+    recordFile(recorder, projectPath, rel, RECORD_KINDS.GATE_SCRIPT);
+    result.written.push(rel);
+  }
+  return result;
+}
+
+const MAX_SHOWN = 12;
+
+/**
+ * Run the installed scanners and print the outcome. Never throws.
+ * @param {string} projectPath
+ * @param {{ staged?: boolean, mode?: 'warn'|'block', log?: Function }} [opts]
+ *   staged — scan only the files staged for commit (what a pre-commit run wants);
+ *            otherwise the whole project (a CI or manual run). Default: staged when
+ *            something is staged, whole project when nothing is.
+ * @returns {{ ran: string[], findings: Record<string, number>, couldNotJudge: string[], blocked: boolean, missing: string[] }}
+ */
+export function runTestQualityGates(projectPath, { staged, mode, log = console.log } = {}) {
+  const result = { ran: [], findings: {}, couldNotJudge: [], blocked: false, missing: [] };
+  const effectiveMode = mode || loadPolicy(projectPath).policy.mode;
+  const blocking = effectiveMode === 'block';
+
+  if (!gateStandardInstalled(projectPath)) return result;
+  if (staged === undefined) {
+    const s = readStagedChanges(projectPath);
+    staged = Array.isArray(s.changes) && s.changes.length > 0;
+  }
+
+  for (const { file, label } of GATE_SCRIPTS) {
+    const rel = destRel(file);
+    const abs = join(projectPath, rel);
+    if (!existsSync(abs)) { result.missing.push(file); continue; }
+
+    const args = [abs, ...(staged ? ['--staged'] : [])];
+    const r = spawnSync(process.execPath, args, { cwd: projectPath, encoding: 'utf-8', timeout: 120000, maxBuffer: 32 * 1024 * 1024 });
+    result.ran.push(file);
+
+    if (r.status === 0) {
+      log(chalk.gray(`  ✓ [${label}] ${rel}: nothing found${staged ? ' in the staged files' : ''}`));
+      // "Nothing found" must not hide what was NOT looked at: the script lists files it could not
+      // judge (a language it has no rule for, an unparsable call) on lines that start with `·`.
+      for (const l of (r.stdout || '').split('\n').filter((x) => /^\s*·/.test(x))) log((/NOT scanned|could not be parsed/.test(l) ? chalk.yellow : chalk.gray)(`    ${l.trim()}`));
+      continue;
+    }
+    if (r.status === 1) {
+      const lines = (r.stdout || '').split('\n').filter((l) => l.trim());
+      const count = lines.filter((l) => /^\s*✗/.test(l)).length;
+      result.findings[label] = count;
+      const head = blocking
+        ? `  ✗ [${label}] BLOCKED: ${rel} found ${count} finding(s) (mode "block").`
+        : `  ⚠ [${label}] ${rel} found ${count} finding(s) — warning only, the commit is not blocked.`;
+      log(blocking ? chalk.red(head) : chalk.yellow(head));
+      const shown = lines.slice(0, MAX_SHOWN + 4);
+      for (const l of shown) log(chalk.gray(`    ${l.trim()}`));
+      if (lines.length > shown.length) log(chalk.gray(`    ... (run \`node ${rel}\` to see everything)`));
+      if (blocking) result.blocked = true;
+      continue;
+    }
+    // exit 2, a crash, a timeout, a missing node: the scanner could not judge. Never a pass.
+    const why = r.error ? r.error.message : (r.stderr || r.stdout || `exit ${r.status}`).split('\n').find((l) => l.trim()) || `exit ${r.status}`;
+    result.couldNotJudge.push(label);
+    const head = blocking
+      ? `  ✗ [${label}] BLOCKED: ${rel} could not judge (mode "block" treats that as a failure): ${why.trim()}`
+      : `  ⚠ [${label}] ${rel} could not judge — this is NOT a pass: ${why.trim()}`;
+    log(blocking ? chalk.red(head) : chalk.yellow(head));
+    if (blocking) result.blocked = true;
+  }
+
+  if (result.missing.length > 0) {
+    log(chalk.gray(`  ℹ [test-gates] ${result.missing.map(destRel).join(', ')} not installed (the full-coverage-testing standard asks for them). \`uds update\` offers to install them.`));
+  }
+  if (result.blocked) process.exitCode = 1;
+  if (result.ran.length > 0 || result.missing.length > 0) log();
+  return result;
+}

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/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;