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

package/src/uninstallers/hook-uninstaller.js

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmdirSync } from 'fs';
 import { join, basename } from 'path';
+import { proveUnchanged, RECORD_KINDS, RECORDS_KEY, isRealDirectory } from '../core/install-records.js';
+import { stripUdsHookBlock } from '../utils/git-hooks.js';
 import {
   collectHookConfigs, standardsSourceDir, hooksSourceDir,
   CODEX_HOOK_SCRIPT, GEMINI_HOOK_SCRIPT, AGY_HOOK_SCRIPT,
@@ -88,7 +90,7 @@ function applyHooksMap(config, nextMap) {
  * difference is which file and which key they look at.
  */
 function uninstallHookConfigFile({ configPath, label, dryRun, deleteEmptyFile }) {
-  const result = { removed: [], skipped: [], errors: [] };
+  const result = { removed: [], skipped: [], errors: [], deletedPaths: [] };
   if (!existsSync(configPath)) return result; // nothing installed here — nothing to report
 
   let config;
@@ -106,18 +108,21 @@ function uninstallHookConfigFile({ configPath, label, dryRun, deleteEmptyFile })
   }
 
   const entryLabel = `${label} (${removedCount} UDS hook ${removedCount === 1 ? 'entry' : 'entries'})`;
+  const updatedConfig = applyHooksMap(config, nextMap);
+  const willDeleteFile = deleteEmptyFile && Object.keys(updatedConfig).length === 0;
+  // Decided BEFORE the dry-run return: the preview must say the file goes away,
+  // and the folder-cleanup step needs to know the folder will be empty.
   if (dryRun) {
-    result.removed.push(entryLabel);
+    result.removed.push(willDeleteFile ? `${entryLabel}, file removed — created by UDS, now empty` : entryLabel);
+    if (willDeleteFile) result.deletedPaths.push(label);
     return result;
   }
 
-  const updatedConfig = applyHooksMap(config, nextMap);
-  const isNowEmpty = Object.keys(updatedConfig).length === 0;
-
   try {
-    if (deleteEmptyFile && isNowEmpty) {
+    if (willDeleteFile) {
       unlinkSync(configPath);
       result.removed.push(`${entryLabel}, file removed — created by UDS, now empty`);
+      result.deletedPaths.push(label);
     } else {
       writeFileSync(configPath, JSON.stringify(updatedConfig, null, 2) + '\n');
       result.removed.push(entryLabel);
@@ -186,7 +191,7 @@ export function uninstallAgyHooks(projectPath, options = {}) {
   const configPath = join(projectPath, '.agents', 'hooks.json');
   const label = '.agents/hooks.json';
   const dryRun = options.dryRun || false;
-  const result = { removed: [], skipped: [], errors: [] };
+  const result = { removed: [], skipped: [], errors: [], deletedPaths: [] };
   if (!existsSync(configPath)) return result;
 
   let config;
@@ -242,14 +247,17 @@ export function uninstallAgyHooks(projectPath, options = {}) {
   }
 
   const entryLabel = `${label} (${removedCount} UDS hook ${removedCount === 1 ? 'entry' : 'entries'})`;
+  const willDeleteFile = Object.keys(next).length === 0;
   if (dryRun) {
-    result.removed.push(entryLabel);
+    result.removed.push(willDeleteFile ? `${entryLabel}, file removed — created by UDS, now empty` : entryLabel);
+    if (willDeleteFile) result.deletedPaths.push(label);
     return result;
   }
   try {
-    if (Object.keys(next).length === 0) {
+    if (willDeleteFile) {
       unlinkSync(configPath);
       result.removed.push(`${entryLabel}, file removed — created by UDS, now empty`);
+      result.deletedPaths.push(label);
     } else {
       writeFileSync(configPath, JSON.stringify(next, null, 2) + '\n');
       result.removed.push(entryLabel);
@@ -260,18 +268,113 @@ export function uninstallAgyHooks(projectPath, options = {}) {
   return result;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Proof of authorship — "only delete what UDS can prove it wrote, unchanged".
+//
+// A record in `manifest.installedArtifacts` (core/install-records.js) says UDS
+// wrote a file; a matching hash says nobody has changed it since. Both are
+// required to delete a whole file. Anything else is KEPT, and the reason is
+// printed, because "not provably ours" is the honest state of a file from an
+// older UDS (no record) or one an adopter has edited (hash differs) — and
+// guessing "probably ours" is how an adopter's own hook script gets deleted.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Relative paths (forward slashes) of every file under `dir`, or [] if it is not there. */
+function listFiles(dir, rel = '') {
+  if (!dir || !existsSync(dir)) return [];
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) out.push(...listFiles(join(dir, e.name), r));
+    else out.push(r);
+  }
+  return out;
+}
+
+/**
+ * Remove the hook scripts UDS copied into `scripts/hooks/`.
+ *
+ * `scripts/hooks/` is a directory UDS scaffolds inside the adopter's project, so
+ * an adopter's own scripts can sit beside ours (a test in hook-uninstaller.test.js
+ * places one there and it must survive). Only files that have an install record
+ * AND still match it are deleted.
+ */
+export function uninstallHookScripts(projectPath, manifest, { dryRun = false, blockedBy = null } = {}) {
+  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)
+    .map(([rel]) => rel)
+    .sort();
+
+  for (const rel of recorded) {
+    const abs = join(projectPath, rel);
+    if (!existsSync(abs)) continue; // already gone — nothing to remove, nothing to report
+    if (blockedBy) {
+      result.skipped.push(`${rel} (kept: ${blockedBy})`);
+      continue;
+    }
+    const proof = proveUnchanged(manifest, projectPath, rel);
+    if (proof.state !== 'proven') {
+      result.skipped.push(`${rel} (kept: ${proof.why})`);
+      continue;
+    }
+    try {
+      if (!dryRun) unlinkSync(abs);
+      result.removed.push(`${rel} (deleted — installed by UDS, ${proof.why})`);
+      result.deletedPaths.push(rel);
+    } catch (error) {
+      result.errors.push(`${rel} — ${error.message}`);
+    }
+  }
+
+  // Files that carry the name of a script UDS ships but have no record. Say so once,
+  // so a leftover `scripts/hooks/` is an explained decision and not a silent gap.
+  const recordedSet = new Set(recorded);
+  const shipped = listFiles(hooksSourceDir());
+  const unrecorded = shipped
+    .map((f) => `scripts/hooks/${f}`)
+    .filter((rel) => existsSync(join(projectPath, rel)) && !recordedSet.has(rel));
+  if (unrecorded.length > 0) {
+    result.skipped.push(
+      `scripts/hooks/ (kept: ${unrecorded.length} file${unrecorded.length === 1 ? '' : 's'} carry the name of a UDS hook script, ` +
+      'but the manifest has no record that UDS wrote them — installed by an older UDS, or by hand. ' +
+      'Delete them yourself if you no longer want them)'
+    );
+  }
+  return result;
+}
+
+// Line-level fallback, for the one-line form older UDS wrote and for a block whose
+// end marker an adopter removed. The current block is removed whole, by its markers
+// (stripUdsHookBlock) — its inner lines are not individually matchable.
+const UDS_PRECOMMIT_LINE = /uds\s+check|universal-dev-standards\s+check|checkin-standards|^#\s*UDS Standard Check\s*$/;
+const NATIVE_UDS_LINE = /uds\s+check|checkin-standards|UDS pre-commit hook/;
+
+/** True when nothing is left but a shebang and blank lines. */
+function nothingButShebang(lines) {
+  return lines.every((l) => !l.trim() || /^#!/.test(l.trim()));
+}
+
 /**
  * Remove UDS-related lines from .husky/pre-commit, the native
  * .git/hooks/pre-commit fallback, and the enforcement-hook entries UDS wrote
  * into .claude/settings.json, .codex/hooks.json, .gemini/settings.json and
- * .agents/hooks.json.
+ * .agents/hooks.json; and the hook scripts copied into scripts/hooks/.
+ *
+ * Whole-file deletion (a hook file, a script) needs proof — see proveUnchanged.
+ * A hook file that is not provably wholly UDS's still has its UDS lines removed
+ * (each is a line UDS wrote, and the rest of the file is untouched) and the
+ * remainder is reported as kept, with the reason.
+ *
  * @param {string} projectPath - Project root path
- * @param {Object} options - { dryRun: boolean }
- * @returns {Object} { removed: string[], skipped: string[], errors: string[] }
+ * @param {Object} options - { dryRun: boolean, manifest: object|null }
+ *   `manifest` must be read BEFORE `.standards/` is removed; it carries the install records.
+ * @returns {Object} { removed: string[], skipped: string[], errors: string[], deletedPaths: string[] }
  */
 export function uninstallHook(projectPath, options = {}) {
-  const { dryRun = false } = options;
-  const result = { removed: [], skipped: [], errors: [] };
+  const { dryRun = false, manifest = null } = options;
+  const result = { removed: [], skipped: [], errors: [], deletedPaths: [] };
   const hookPath = join(projectPath, '.husky', 'pre-commit');
 
   if (!existsSync(hookPath)) {
@@ -279,12 +382,23 @@ export function uninstallHook(projectPath, options = {}) {
   } else {
     try {
       const content = readFileSync(hookPath, 'utf-8');
+      const proof = proveUnchanged(manifest, projectPath, '.husky/pre-commit');
       const lines = content.split('\n');
-      const udsPattern = /uds\s+check|checkin-standards/;
-      const filteredLines = lines.filter(line => !udsPattern.test(line));
+      const filteredLines = stripUdsHookBlock(content).content.split('\n')
+        .filter(line => !UDS_PRECOMMIT_LINE.test(line));
 
-      if (filteredLines.length === lines.length) {
+      if (proof.state === 'proven') {
+        // UDS created this file and nobody has touched it: nothing of the adopter's is in it.
+        if (!dryRun) unlinkSync(hookPath);
+        result.removed.push(`.husky/pre-commit (deleted — created by UDS, ${proof.why})`);
+        result.deletedPaths.push('.husky/pre-commit');
+      } else if (filteredLines.length === lines.length) {
         result.skipped.push('.husky/pre-commit (no UDS lines found)');
+      } else if (nothingButShebang(filteredLines)) {
+        // Only UDS's lines (and a shebang) were in it — removing them leaves nothing worth keeping.
+        if (!dryRun) unlinkSync(hookPath);
+        result.removed.push('.husky/pre-commit (UDS check lines; file removed — nothing else was in it)');
+        result.deletedPaths.push('.husky/pre-commit');
       } else if (dryRun) {
         result.removed.push('.husky/pre-commit (UDS check lines)');
       } else {
@@ -301,25 +415,30 @@ export function uninstallHook(projectPath, options = {}) {
   if (existsSync(nativeHookPath)) {
     try {
       const content = readFileSync(nativeHookPath, 'utf-8');
-      const udsPattern = /uds\s+check|checkin-standards|UDS pre-commit hook/;
+      const proof = proveUnchanged(manifest, projectPath, '.git/hooks/pre-commit');
 
-      if (!udsPattern.test(content)) {
+      if (proof.state === 'proven') {
+        // The whole script is what `uds init` wrote — including the parts no line
+        // pattern would ever match (its "Auto-generated by uds init" header, the
+        // linter fallbacks, the closing echo). Deleting only the matching lines
+        // used to leave that body behind, still executable, still claiming
+        // "Pre-commit checks passed".
+        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)) {
         result.skipped.push('.git/hooks/pre-commit (no UDS lines found)');
-      } else if (dryRun) {
-        result.removed.push('.git/hooks/pre-commit (UDS native hook)');
       } else {
-        // Remove only UDS-related lines, keep other hook content
         const lines = content.split('\n');
-        const filtered = lines.filter(line => !udsPattern.test(line));
-
-        // If only shebang remains, remove the file entirely; otherwise rewrite
-        const nonEmpty = filtered.filter(l => l.trim() && l.trim() !== '#!/bin/sh');
-        if (nonEmpty.length === 0) {
-          unlinkSync(nativeHookPath);
+        const filtered = lines.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)');
+          result.deletedPaths.push('.git/hooks/pre-commit');
         } else {
-          writeFileSync(nativeHookPath, filtered.join('\n'), 'utf-8');
+          if (!dryRun) writeFileSync(nativeHookPath, filtered.join('\n'), 'utf-8');
           result.removed.push('.git/hooks/pre-commit (UDS lines removed)');
+          result.skipped.push(`.git/hooks/pre-commit (kept: the rest of the script — ${proof.why})`);
         }
       }
     } catch (error) {
@@ -329,16 +448,81 @@ export function uninstallHook(projectPath, options = {}) {
 
   // Enforcement hooks written by installHooks()/installCodexHooks()/installGeminiHooks()
   // — the gap this function used to have entirely (see module doc comment above).
-  for (const sub of [
+  const configResults = [
     uninstallClaudeCodeHooks(projectPath, { dryRun }),
     uninstallCodexHooks(projectPath, { dryRun }),
     uninstallGeminiHooks(projectPath, { dryRun }),
     uninstallAgyHooks(projectPath, { dryRun }),
-  ]) {
+  ];
+  for (const sub of configResults) {
     result.removed.push(...sub.removed);
     result.skipped.push(...sub.skipped);
     result.errors.push(...sub.errors);
+    result.deletedPaths.push(...sub.deletedPaths);
   }
 
+  // The scripts those entries ran. If a config file could not be cleaned (it still
+  // names a script), deleting the script would turn a working hook into a failing one.
+  const configFailed = configResults.some((r) => r.errors.length > 0);
+  const scripts = uninstallHookScripts(projectPath, manifest, {
+    dryRun,
+    blockedBy: configFailed ? 'a hook config file could not be cleaned (see the error above) and still runs this script' : null
+  });
+  result.removed.push(...scripts.removed);
+  result.skipped.push(...scripts.skipped);
+  result.errors.push(...scripts.errors);
+  result.deletedPaths.push(...scripts.deletedPaths);
+
+  return result;
+}
+
+/**
+ * Remove the folders UDS had to create for its files (`.codex/`, `scripts/hooks/`, ...),
+ * once they are empty.
+ *
+ * A folder is removed only if (a) the manifest recorded that UDS created it and
+ * (b) nothing is left in it. An empty `.codex/` that the adopter made themselves is
+ * indistinguishable by looking; the record is the only thing that tells them apart.
+ * A folder that still holds anything — `.agents/rules/style.md` — is kept and
+ * reported, so the adopter sees why it stayed.
+ *
+ * In a dry run nothing has been deleted yet, so `plannedDeletions` (relative paths
+ * the run WOULD delete) stands in for the missing deletions when judging "empty".
+ *
+ * @param {string} projectPath
+ * @param {Object|null} manifest - read before `.standards/` was removed
+ * @param {{ dryRun?: boolean, plannedDeletions?: string[] }} [options]
+ * @returns {{ removed: string[], skipped: string[], errors: string[], deletedPaths: string[] }}
+ */
+export function pruneCreatedDirs(projectPath, manifest, { dryRun = false, plannedDeletions = [] } = {}) {
+  const result = { removed: [], skipped: [], errors: [], deletedPaths: [] };
+  const dirs = manifest?.[RECORDS_KEY]?.createdDirs || [];
+  const gone = new Set(plannedDeletions.map((p) => p.replace(/\\/g, '/')));
+  // Deepest first: `scripts/hooks` must go before `scripts` can be seen as empty.
+  const ordered = [...new Set(dirs)]
+    .filter((d) => d && !d.startsWith('..') && !d.startsWith('/'))
+    .sort((a, b) => b.split('/').length - a.split('/').length);
+
+  for (const rel of ordered) {
+    const abs = join(projectPath, rel);
+    if (!existsSync(abs)) continue;
+    if (!isRealDirectory(abs)) {
+      result.skipped.push(`${rel}/ (kept: not a plain directory)`);
+      continue;
+    }
+    try {
+      const left = readdirSync(abs).filter((name) => !gone.has(`${rel}/${name}`));
+      if (left.length > 0) {
+        result.skipped.push(`${rel}/ (kept: created by UDS but not empty — still holds ${left.slice(0, 3).join(', ')}${left.length > 3 ? ', ...' : ''}, which UDS did not write)`);
+        continue;
+      }
+      if (!dryRun) rmdirSync(abs);
+      gone.add(rel);
+      result.removed.push(`${rel}/ (empty folder created by UDS, removed)`);
+      result.deletedPaths.push(rel);
+    } catch (error) {
+      result.errors.push(`${rel}/ — ${error.message}`);
+    }
+  }
   return result;
 }

package/src/uninstallers/integration-uninstaller.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import { extractMarkedContent } from '../utils/integration-generator.js';
 import { SUPPORTED_AI_TOOLS } from '../core/constants.js';
 import { resolveIntegrationFile } from '../core/constants.js';
+import { proveUnchanged } from '../core/install-records.js';
 
 /**
  * Get the format for a given integration file name
@@ -29,7 +30,7 @@ function getFormatForFile(fileName) {
  */
 export async function uninstallIntegrations(projectPath, manifest, options = {}) {
   const { dryRun = false, interactive = false, promptFn = null } = options;
-  const result = { removed: [], skipped: [], errors: [] };
+  const result = { removed: [], skipped: [], errors: [], deletedPaths: [] };
 
   const integrations = manifest?.integrations || [];
   if (integrations.length === 0) {
@@ -64,11 +65,27 @@ export async function uninstallIntegrations(projectPath, manifest, options = {})
       const userContent = (parts.before.trim() + parts.after.trim()).trim();
       const hasUserContent = userContent.length > 0;
 
+      // Text outside the UDS block is not automatically the adopter's. A file UDS
+      // creates from nothing carries generated text there — AGENTS.md's
+      // "> Auto-generated by ..." header and sections, CLAUDE.md's leading guidance —
+      // and treating all of it as "user content" left an orphaned file pointing at
+      // the `.standards/` this very command removes. It is only "not the adopter's"
+      // if UDS recorded a hash of it when it created the file and the text still
+      // matches; without that proof it stays, and the reason is printed.
+      const proof = hasUserContent ? proveUnchanged(manifest, projectPath, fileName) : null;
+      const outsideIsUdsOwn = hasUserContent && proof.state === 'proven';
+      const keptNote = () => `${fileName} (kept: the text outside the UDS block — ${proof.why})`;
+
       if (dryRun) {
-        if (hasUserContent) {
-          result.removed.push(`${fileName} (remove UDS block, keep user content)`);
-        } else {
+        if (!hasUserContent) {
           result.removed.push(`${fileName} (delete file)`);
+          result.deletedPaths.push(fileName);
+        } else if (outsideIsUdsOwn) {
+          result.removed.push(`${fileName} (delete file — everything outside the UDS block was generated by UDS)`);
+          result.deletedPaths.push(fileName);
+        } else {
+          result.removed.push(`${fileName} (remove UDS block, keep user content)`);
+          result.skipped.push(keptNote());
         }
         continue;
       }
@@ -77,26 +94,39 @@ export async function uninstallIntegrations(projectPath, manifest, options = {})
         // 100% UDS-generated → delete entire file
         unlinkSync(filePath);
         result.removed.push(`${fileName} (deleted)`);
+        result.deletedPaths.push(fileName);
+      } else if (outsideIsUdsOwn) {
+        // UDS created this file and its non-block text is still exactly what UDS
+        // wrote: there is no adopter content to preserve, so no question to ask.
+        unlinkSync(filePath);
+        result.removed.push(`${fileName} (deleted — everything outside the UDS block was generated by UDS and is unchanged)`);
+        result.deletedPaths.push(fileName);
       } else if (interactive && promptFn) {
         // Ask user what to do
         const action = await promptFn(fileName, hasUserContent);
         if (action === 'delete-file') {
           unlinkSync(filePath);
           result.removed.push(`${fileName} (deleted)`);
+          result.deletedPaths.push(fileName);
         } else if (action === 'remove-block') {
           const cleaned = (parts.before + parts.after).trim() + '\n';
           writeFileSync(filePath, cleaned, 'utf-8');
           result.removed.push(`${fileName} (UDS block removed)`);
+          result.skipped.push(keptNote());
         } else {
           result.skipped.push(`${fileName} (user skipped)`);
         }
       } else {
-        // Non-interactive (--yes): remove UDS block only, preserve user content
+        // Non-interactive (--yes): remove UDS block only, preserve everything else
         const cleaned = (parts.before + parts.after).trim() + '\n';
         writeFileSync(filePath, cleaned, 'utf-8');
         result.removed.push(`${fileName} (UDS block removed)`);
+        result.skipped.push(keptNote());
       }
     } catch (error) {
+      // A closed prompt is the user stopping the run, not a failure of this file:
+      // let the command report it (and exit non-zero) instead of retrying the next file.
+      if (error?.name === 'ExitPromptError') throw error;
       result.errors.push(`${fileName} — ${error.message}`);
     }
   }

package/src/utils/git-hooks.js

@@ -11,6 +11,7 @@
  * adopters (asiaostrich-telemetry-server, asiaostrich-telemetry-client,
  * machine-setup): all three have `.husky/pre-commit` calling `npx uds check`,
  * none has `core.hooksPath` set, and the hook has never once run.
+ * (That `npx uds check` form was itself replaced — see buildPreCommitBlock.)
  *
  * Fix: set `core.hooksPath` directly ourselves. This is exactly what husky's
  * own `index.js` does internally (verified against husky ^9.1.7's source:
@@ -94,7 +95,7 @@ export function wireGitHooksPath(projectPath, targetRelDir) {
     return {
       wired: false,
       reason: `git core.hooksPath is already set to "${configured}"`,
-      hint: `UDS will not override an existing core.hooksPath. Confirm the hook script there also runs \`npx uds check\`, or switch it yourself: git config --local core.hooksPath ${targetRelDir}`
+      hint: `UDS will not override an existing core.hooksPath. Confirm the hook script there also runs \`universal-dev-standards check\` (the installed CLI — not the short name "uds", which on the npm registry is an unrelated package), or switch it yourself: git config --local core.hooksPath ${targetRelDir}`
     };
   }
 
@@ -107,7 +108,7 @@ export function wireGitHooksPath(projectPath, targetRelDir) {
     return {
       wired: false,
       reason: '.git/hooks/pre-commit already exists',
-      hint: 'UDS will not overwrite or bypass an existing .git/hooks/pre-commit. Add "npx uds check" to it manually, or remove it and re-run `uds init`.'
+      hint: 'UDS will not overwrite or bypass an existing .git/hooks/pre-commit. Add a "universal-dev-standards check" line to it manually (it needs the UDS CLI installed in this project or on PATH), or remove it and re-run `uds init`.'
     };
   }
 
@@ -126,10 +127,129 @@ export function wireGitHooksPath(projectPath, targetRelDir) {
   }
 }
 
-/** Does `filePath` contain the marker UDS writes into a hook it manages? */
+// ─────────────────────────────────────────────────────────────────────────────
+// What UDS writes into `.husky/pre-commit`.
+//
+// 🔴 This used to be the single line `npx uds check`. `npx` resolves a bare
+// command name from node_modules/.bin and PATH first, and only when neither has
+// it does it go to the npm registry — and the registry package named `uds` is
+// NOT this project (it is an unrelated package by another maintainer, no
+// `bin`, last published 2022). So a clone with no UDS installed had a commit
+// hook that asked npm for a stranger's package by name. It failed today only
+// because that package has no executable; the day its owner publishes one with a
+// `uds` bin, every adopter's every commit runs the stranger's code.
+//
+// Measured 2026-09-30 against a local fake registry that logs each request
+// (npm 10.9.9, 11.20.0, 12.1.0 — identical): `npx --no-install uds` STILL fetches
+// the package metadata for `uds` (GET /uds), so `--no-install` is not a fix; and
+// `npx --no-install --package=universal-dev-standards uds` does not find a
+// GLOBAL install at all (it goes to the registry for our own name and fails).
+// Neither is usable, so the hook does not involve npm at all: it looks in this
+// project's node_modules/.bin, then on PATH, and it looks for the bin named
+// after the full package name — `universal-dev-standards` is a name only this
+// project can publish, `uds` is a name anyone's package can also claim.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** First line of the block UDS writes (also the marker older UDS versions wrote). */
+export const UDS_HOOK_MARKER = '# UDS Standard Check';
+/** Last line of the block — lets uninstall remove the whole block, not guess line by line. */
+export const UDS_HOOK_END_MARKER = '# End UDS Standard Check';
+/** The bin every UDS release has shipped since the rename; named after the package on purpose. */
+export const UDS_BIN_NAME = 'universal-dev-standards';
+/** A hook line that runs the UDS check — the old short form or the current full-name form. */
+export const UDS_CHECK_COMMAND_RE = /\b(?:uds|universal-dev-standards)\s+check\b/;
+
+/**
+ * Any place a hook script runs the bare name `uds` through a package runner
+ * (npx, bunx, pnpm dlx, yarn dlx, npm exec ...). Broader than the two exact lines UDS
+ * ever wrote (see legacy-hook-migration.js): this finds lines to TELL the
+ * adopter about, not lines UDS may change.
+ */
+export const BARE_UDS_RUNNER_RE = /\b(?:npx|bunx|pnpx|pnpm\s+dlx|yarn\s+dlx|npm\s+exec|npm\s+x)\s+(?:-\S+\s+)*uds\b/;
+
+/** Does this hook script still run the bare name `uds` through a package runner? */
+export function hasBareUdsRunner(content) {
+  return typeof content === 'string' && content.split('\n').some((l) => BARE_UDS_RUNNER_RE.test(l));
+}
+
+/** Does hook script `content` run the UDS check, in either the old or the current form? */
+export function hookRunsUdsCheck(content) {
+  return typeof content === 'string' && UDS_CHECK_COMMAND_RE.test(content);
+}
+
+/**
+ * The block `uds init` appends to `.husky/pre-commit` (and `uds update` swaps in
+ * for the old one-liner). POSIX sh; runs in git-bash on Windows.
+ *
+ * - The subshell keeps the PATH change from leaking into the adopter's own
+ *   commands in the same hook file.
+ * - `|| exit $?` makes both outcomes stop the commit even when the adopter has
+ *   put more commands after this block. Without it the "not installed" branch
+ *   would be a silent skip of the check, which is what this must never be.
+ * - 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).
+ * @returns {string} the block, LF line endings, ending with a newline
+ */
+export function buildPreCommitBlock({ args = '' } = {}) {
+  const cmd = args ? `${UDS_BIN_NAME} check ${args}` : `${UDS_BIN_NAME} check`;
+  return [
+    UDS_HOOK_MARKER,
+    '# Runs the UDS CLI installed in this project (node_modules/.bin) or on PATH.',
+    '# It never asks npm to fetch anything: the short name "uds" on the npm registry',
+    '# belongs to an unrelated package, and npx would download and run it.',
+    '(',
+    '  PATH="$PWD/node_modules/.bin:$PATH"',
+    `  if command -v ${UDS_BIN_NAME} >/dev/null 2>&1; then`,
+    `    ${cmd}`,
+    '    exit $?',
+    '  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',
+    '  exit 1',
+    ') || exit $?',
+    UDS_HOOK_END_MARKER,
+    ''
+  ].join('\n');
+}
+
+/**
+ * Remove the block buildPreCommitBlock() writes — from the marker line through
+ * the end-marker line, inclusive — and nothing else. A block whose end marker is
+ * gone (the adopter cut into it) is left alone: what remains of it is no longer
+ * provably UDS's, and the caller's line-level fallback deals with the lines it can name.
+ * @returns {{content: string, removed: boolean}}
+ */
+export function stripUdsHookBlock(content) {
+  const lines = content.split('\n');
+  const out = [];
+  let removed = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === UDS_HOOK_MARKER) {
+      let end = -1;
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === UDS_HOOK_END_MARKER) { end = j; break; }
+        // Another marker before an end marker means this block is not well-formed.
+        if (lines[j].trim() === UDS_HOOK_MARKER) break;
+      }
+      if (end !== -1) {
+        i = end;
+        removed = true;
+        continue;
+      }
+    }
+    out.push(lines[i]);
+  }
+  return { content: out.join('\n'), removed };
+}
+
+/** Does `filePath` contain a hook line UDS manages (the old one-liner or the current block)? */
 function hasUdsMarker(filePath) {
   try {
-    return readFileSync(filePath, 'utf-8').includes('uds check');
+    return hookRunsUdsCheck(readFileSync(filePath, 'utf-8'));
   } catch {
     return false;
   }
@@ -225,7 +345,7 @@ export function stripLegacyHuskyShLine(content) {
  * @param {string} projectPath
  * @returns {{relevant: boolean, wired?: boolean, hookFile?: string,
  *   configuredHooksPath?: string|null, effectiveHooksDir?: string|null,
- *   legacyV8?: boolean, missingShebang?: boolean}}
+ *   legacyV8?: boolean, missingShebang?: boolean, legacyBareUds?: boolean}}
  *   `relevant: false` means there is nothing UDS-managed to report on (no
  *   hook file, or hooks-dir could not be determined — never guess "unwired"
  *   from a failed lookup).
@@ -252,6 +372,13 @@ export function checkPreCommitHookWiring(projectPath) {
     try { return !hasShebang(readFileSync(managedPath, 'utf-8')); } catch { return false; }
   })();
 
+  // Independent of wiring, like missingShebang: the file can be wired and still ask
+  // npm for the bare name `uds` (see buildPreCommitBlock). Only the husky file is
+  // examined — that is the one UDS wrote the old one-liner into.
+  const legacyBareUds = hasHuskyHook && (() => {
+    try { return hasBareUdsRunner(readFileSync(huskyHookPath, 'utf-8')); } catch { return false; }
+  })();
+
   const effectiveFile = join(effectiveHooksDir, 'pre-commit');
   let wired = false;
   if (existsSync(effectiveFile)) {
@@ -264,7 +391,7 @@ export function checkPreCommitHookWiring(projectPath) {
     }
   }
 
-  if (wired) return { relevant: true, wired: true, hookFile, missingShebang };
+  if (wired) return { relevant: true, wired: true, hookFile, missingShebang, legacyBareUds };
 
   const legacyV8 = hasHuskyHook && (() => {
     try { return hasLegacyHuskyShLine(readFileSync(huskyHookPath, 'utf-8')); } catch { return false; }
@@ -277,6 +404,7 @@ export function checkPreCommitHookWiring(projectPath) {
     configuredHooksPath: getLocalHooksPathConfig(projectPath),
     effectiveHooksDir,
     legacyV8,
-    missingShebang
+    missingShebang,
+    legacyBareUds
   };
 }