universal-dev-standards 6.14.0-beta.3 → 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 = {
@@ -249,18 +260,17 @@ async function executeCreateOrUpdate(projectPath, action, manifest) {
       let targetDir = '.standards';
 
       if (metadata?.extensionSource) {
-        // An entry from `manifest.extensions`. PathResolver cannot resolve these
-        // from an npm install: the published package's `files` list is bin, src,
-        // bundled, standards-registry.json and README.md — no `extensions/`. So
-        // `sourcePath` is null for every adopter who did not install from a
-        // source checkout, and this function answered "No source path available"
-        // for a file it was perfectly able to fetch.
+        // An entry from `manifest.extensions`. It is resolved from the installed
+        // package (`bundled/extensions/`, shipped since XSPEC-452) — never from GitHub.
+        // `copyStandard` hands any `extensions/` path to `copyExtension`, which fails
+        // by name when the package lacks the file, instead of downloading it.
         //
-        // The legacy update path never had the bug because it calls copyStandard
-        // directly (`update.js`, "Update extensions"). The same upgrade therefore
-        // refreshed `.standards/zh-tw.md` under `uds update` and failed under the
-        // reconciler — the two paths disagreed about whether the file was
-        // reachable, and only one of them was right. (XSPEC-343)
+        // History: before XSPEC-452 the published package had no `extensions/`, so
+        // `sourcePath` was null for every adopter who did not install from a source
+        // checkout, and this function answered "No source path available" for a file it
+        // could fetch from GitHub. The legacy update path (`update.js`, "Update
+        // extensions") was the one that worked — only because it fell back to a
+        // download. (XSPEC-343)
         sourceStr = metadata.extensionSource;
       } else if (metadata?.registryEntry) {
         const source = metadata.registryEntry.source;
@@ -423,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();
 
@@ -426,11 +427,13 @@ export function uninstallHook(projectPath, options = {}) {
         if (!dryRun) unlinkSync(nativeHookPath);
         result.removed.push(`.git/hooks/pre-commit (UDS native hook, file removed — ${proof.why})`);
         result.deletedPaths.push('.git/hooks/pre-commit');
-      } else if (!NATIVE_UDS_LINE.test(content)) {
+      } else if (!NATIVE_UDS_LINE.test(content) && !stripUdsHookBlock(content).removed) {
         result.skipped.push('.git/hooks/pre-commit (no UDS lines found)');
       } else {
-        const lines = content.split('\n');
-        const filtered = lines.filter(line => !NATIVE_UDS_LINE.test(line));
+        // The block the native hook carries is removed whole, by its markers — its
+        // inner lines are not individually matchable (same as the husky path above).
+        const filtered = stripUdsHookBlock(content).content.split('\n')
+          .filter(line => !NATIVE_UDS_LINE.test(line));
         if (nothingButShebang(filtered)) {
           if (!dryRun) unlinkSync(nativeHookPath);
           result.removed.push('.git/hooks/pre-commit (UDS native hook, file removed)');

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';
@@ -26,15 +26,92 @@ function getSourcePath(sourcePath) {
   return PathResolver.getStandardSource(sourcePath);
 }
 
+/**
+ * Is this source path one of the add-on files under `extensions/`?
+ * @param {string} sourcePath - Relative path from repo root
+ * @returns {boolean}
+ */
+export function isExtensionPath(sourcePath) {
+  return typeof sourcePath === 'string' && sourcePath.replace(/\\/g, '/').startsWith('extensions/');
+}
+
+/**
+ * Copy an extension file (language style guide, framework pattern, locale pack)
+ * into the target project — from the installed package ONLY.
+ *
+ * 🔴 There is deliberately no download fallback here (XSPEC-452 R2). `extensions/`
+ * used to be missing from the npm package, so the copy below fell through to
+ * `raw.githubusercontent.com/.../main`: offline installs failed, an install pulled
+ * whatever `main` held that day instead of the version the adopter had installed,
+ * and a file that did not exist anywhere (`extensions/locales/zh-cn.md`, XSPEC-451)
+ * hid behind that fallback until someone ran the locale. A declared extension that
+ * is not in the package is a packaging defect, so it fails — by name.
+ *
+ * @param {string} sourcePath - Relative path from repo root (e.g., 'extensions/locales/zh-tw.md')
+ * @param {string} targetDir - Target directory (usually '.standards')
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Result with success status and copied path
+ */
+export async function copyExtension(sourcePath, targetDir, projectPath) {
+  try {
+    const source = getSourcePath(sourcePath);
+    if (!source) {
+      return failure(
+        `Extension file not found in the installed package: ${sourcePath} (extension files are never downloaded; reinstall or upgrade universal-dev-standards)`,
+        ERROR_CODES.FILE_NOT_FOUND,
+        { sourcePath, targetDir }
+      );
+    }
+    const targetFolder = join(projectPath, targetDir);
+    const targetFile = join(targetFolder, basename(sourcePath));
+    if (!existsSync(targetFolder)) {
+      mkdirSync(targetFolder, { recursive: true });
+    }
+    copyFileSync(source, targetFile);
+    return success(targetFile, { source: 'local', sourcePath, targetFile });
+  } catch (error) {
+    return failure(
+      error.message,
+      ERROR_CODES.FILE_COPY_FAILED,
+      { 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
+ * (except for `extensions/` files, which are package-only — see copyExtension)
  * @param {string} sourcePath - Relative path from repo root (e.g., 'core/anti-hallucination.md')
  * @param {string} targetDir - Target directory (usually '.standards')
  * @param {string} projectPath - Project root path
  * @returns {Promise<Object>} Result with success status and copied path
  */
 export async function copyStandard(sourcePath, targetDir, projectPath) {
+  // Extensions never take the GitHub fallback below, whichever caller got here (XSPEC-452 R2).
+  if (isExtensionPath(sourcePath)) {
+    return copyExtension(sourcePath, targetDir, projectPath);
+  }
   try {
     const targetFolder = join(projectPath, targetDir);
     const targetFile = join(targetFolder, basename(sourcePath));

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/git-hooks.js

@@ -189,11 +189,15 @@ export function hookRunsUdsCheck(content) {
  * - Not installed: say what is missing and how to fix it, exit non-zero. It
  *   neither skips the check nor downloads anything.
  *
- * @param {{args?: string}} [opts] extra arguments to keep on the check command
- *   (e.g. `--standard checkin-standards`, which older UDS versions wrote).
+ * @param {{args?: string, hookFile?: string}} [opts]
+ *   args     — extra arguments to keep on the check command
+ *              (e.g. `--standard checkin-standards`, which older UDS versions wrote).
+ *   hookFile — the file the block is written into, named in the "blocked" message so
+ *              it points at the file the adopter actually has (default `.husky/pre-commit`;
+ *              the native hook passes `.git/hooks/pre-commit`).
  * @returns {string} the block, LF line endings, ending with a newline
  */
-export function buildPreCommitBlock({ args = '' } = {}) {
+export function buildPreCommitBlock({ args = '', hookFile = '.husky/pre-commit' } = {}) {
   const cmd = args ? `${UDS_BIN_NAME} check ${args}` : `${UDS_BIN_NAME} check`;
   return [
     UDS_HOOK_MARKER,
@@ -208,7 +212,7 @@ export function buildPreCommitBlock({ args = '' } = {}) {
     '  fi',
     `  echo "[UDS] Pre-commit check cannot run: the UDS CLI (${UDS_BIN_NAME}) is not installed." >&2`,
     `  echo "[UDS] Install it:  npm install --save-dev ${UDS_BIN_NAME}   (or: npm install -g ${UDS_BIN_NAME})" >&2`,
-    '  echo "[UDS] This commit is blocked until it is installed, or until you remove this block from .husky/pre-commit." >&2',
+    `  echo "[UDS] This commit is blocked until it is installed, or until you remove this block from ${hookFile}." >&2`,
     '  exit 1',
     ') || exit $?',
     UDS_HOOK_END_MARKER,