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

package/src/i18n/messages.js

@@ -875,7 +875,7 @@ export const messages = {
         // Pre-commit hook wiring (XSPEC: uds init writes a hook but never
         // confirmed git would run it — this reports the gap, read-only)
         hookNotWiredTitle: '⚠ [pre-commit] {file} was installed, but git will not run it.',
-        hookNotWiredOverride: '  git core.hooksPath is set to "{path}" — UDS will not override it. Confirm the hook there also runs `npx uds check`, or switch it yourself: git config --local core.hooksPath .husky',
+        hookNotWiredOverride: '  git core.hooksPath is set to "{path}" — UDS will not override it. Confirm the hook 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 .husky',
         hookNotWiredUnwired: '  git core.hooksPath is not set, and {file} is not on git\'s default hook path.',
         hookNotWiredFix: '  Fix (per-clone — not committed, teammates must repeat it): git config --local core.hooksPath .husky',
         hookNotWiredFixNative: '  Fix: point core.hooksPath back to the default (git config --local --unset core.hooksPath), or add `uds check` under "{path}" instead.',
@@ -892,6 +892,8 @@ export const messages = {
         // file or directory". Measured 2026-09-27 in CI (windows-latest).
         hookMissingShebangTitle: '⚠ [pre-commit] {file} has no shebang line — git cannot run it on Windows.',
         hookMissingShebangFix: '  Fix: add a `#!/bin/sh` shebang as the very first line of {file} (a husky-managed hook gets this automatically the next time `uds init` touches it), or re-run `uds init`.',
+        hookBareUdsTitle: '⚠ [pre-commit] {file} asks npm to run the bare name "uds", which on the npm registry is an unrelated package (not this project).',
+        hookBareUdsFix: '  Fix: run `uds update` — it replaces the line UDS itself wrote with one that only runs the installed UDS CLI. A line you wrote or edited yourself is left alone; change it to `universal-dev-standards check`.',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS Status Summary',
@@ -930,6 +932,7 @@ export const messages = {
         title: 'Universal Development Standards - Initialize',
         alreadyInitialized: '⚠ Standards already initialized in this project.',
         useUpdateOrDelete: 'Use `uds update` to update, or delete .standards/ to reinitialize.',
+        useUpdateWithHooks: 'To add enforcement hooks to this project (including for tools UDS began supporting after you initialized), run `uds update --with-hooks`.',
         // Detection
         detectingProject: 'Detecting project characteristics...',
         analysisComplete: 'Project analysis complete',
@@ -1037,6 +1040,11 @@ export const messages = {
         currentVersion: 'Current version',
         latestVersion: 'Latest version',
         upToDate: '✓ Standards are up to date.',
+        // Pre-commit hook migration (bare-name `uds` on the npm registry is not this project)
+        hookMigrated: '✓ .husky/pre-commit: replaced the line an older UDS wrote (it asked npm to resolve the bare name "uds", which is not this project) with one that runs only the installed UDS CLI.',
+        hookWouldMigrate: '+ .husky/pre-commit: would replace the line an older UDS wrote (it asks npm to resolve the bare name "uds", which is not this project) with one that runs only the installed UDS CLI.',
+        hookLegacyKept: '⚠ .husky/pre-commit line {line} ("{text}") asks npm to resolve the bare name "uds", which on the npm registry is an unrelated package. UDS did not write this exact line, so it was left alone. Change it to "universal-dev-standards check" — it needs the UDS CLI installed in this project or on PATH.',
+        hookMigrateFailed: '⚠ Could not rewrite .husky/pre-commit: {error}. The line that asks npm for the bare name "uds" is still there — change it to "universal-dev-standards check".',
         newerVersion: '(You have a newer version than the registry: {version})',
         updateAvailable: 'Update available: {current} → {latest}',
         // Files
@@ -1263,7 +1271,11 @@ export const messages = {
         uninstallPartial: '⚠ Uninstall completed with errors.',
         removed: 'Removed',
         skippedLabel: 'Skipped',
-        errorsLabel: 'Errors'
+        errorsLabel: 'Errors',
+        cannotPrompt: 'Cannot ask for confirmation: nothing is attached to answer the prompt (non-interactive shell, CI, or a pipe).',
+        cannotPromptHint: 'Nothing has been changed. Re-run with --yes to confirm up front, or with --dry-run to preview the changes.',
+        promptClosed: 'The prompt was closed before an answer was given. Nothing has been changed.',
+        promptClosedMidRun: 'A prompt was closed part-way through. Steps already completed stay done; run `uds uninstall` again to finish.'
       }
     }
   },
@@ -2134,7 +2146,7 @@ export const messages = {
         missingSkillsHint: '提示：執行 `uds update` 安裝缺少的 Skills/斜線命令',
         // 提交前檢查是否真的會被 git 執行（uds init 寫了檢查檔，卻沒確認 git 會跑它——這裡只回報，不寫入）
         hookNotWiredTitle: '⚠ [pre-commit] {file} 已安裝，但 git 實際不會執行它。',
-        hookNotWiredOverride: '  git core.hooksPath 已設定為「{path}」——UDS 不會覆蓋它。請確認該路徑下的檔案也會執行 `npx uds check`，或自行改用：git config --local core.hooksPath .husky',
+        hookNotWiredOverride: '  git core.hooksPath 已設定為「{path}」——UDS 不會覆蓋它。請確認該路徑下的檔案也會執行 `universal-dev-standards check`（要用已安裝的 CLI——不要用短名稱 uds，它在 npm registry 上是不相干的套件），或自行改用：git config --local core.hooksPath .husky',
         hookNotWiredUnwired: '  git core.hooksPath 未設定，而 {file} 也不在 git 預設會讀取的路徑上。',
         hookNotWiredFix: '  修復方式（僅對此 clone 生效，不會進版控，其他人 clone 後要自己再跑一次）：git config --local core.hooksPath .husky',
         hookNotWiredFixNative: '  修復方式：把 core.hooksPath 改回預設（git config --local --unset core.hooksPath），或改在「{path}」底下也加上 `uds check`。',
@@ -2150,6 +2162,8 @@ export const messages = {
         // 2026-09-27 於 CI（windows-latest）實測。
         hookMissingShebangTitle: '⚠ [pre-commit] {file} 沒有 shebang 行——在 Windows 上 git 無法執行它。',
         hookMissingShebangFix: '  修復方式：在 {file} 的第一行加上 shebang `#!/bin/sh`（由 husky 管理的 hook，下次 `uds init` 動到它時會自動處理），或重新執行 `uds init`。',
+        hookBareUdsTitle: '⚠ [pre-commit] {file} 會請 npm 執行裸名稱 uds，而它在 npm registry 上是不相干的套件（不是本專案）。',
+        hookBareUdsFix: '  修復方式：執行 `uds update`——它會把 UDS 自己寫入的那一行換成只執行已安裝 UDS CLI 的寫法。你自己寫或改過的那一行不會被動，請自行改成 `universal-dev-standards check`。',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS 狀態摘要',
@@ -2188,6 +2202,7 @@ export const messages = {
         title: '通用開發標準 - 初始化',
         alreadyInitialized: '⚠ 此專案已初始化標準。',
         useUpdateOrDelete: '使用 `uds update` 更新，或刪除 .standards/ 重新初始化。',
+        useUpdateWithHooks: '要為這個專案補裝執行關卡（含 UDS 在你初始化之後才支援的工具），請執行 `uds update --with-hooks`。',
         // Detection
         detectingProject: '正在偵測專案特性...',
         analysisComplete: '專案分析完成',
@@ -2292,6 +2307,11 @@ export const messages = {
         currentVersion: '目前版本',
         latestVersion: '最新版本',
         upToDate: '✓ 標準已是最新版本。',
+        // pre-commit hook 遷移（npm registry 上的裸名稱 uds 不是本專案）
+        hookMigrated: '✓ .husky/pre-commit：已把舊版 UDS 寫入的那一行（它會請 npm 解析裸名稱 uds，而那不是本專案）換成只執行已安裝 UDS CLI 的寫法。',
+        hookWouldMigrate: '+ .husky/pre-commit：將把舊版 UDS 寫入的那一行（它會請 npm 解析裸名稱 uds，而那不是本專案）換成只執行已安裝 UDS CLI 的寫法。',
+        hookLegacyKept: '⚠ .husky/pre-commit 第 {line} 行（「{text}」）會請 npm 解析裸名稱 uds，而它在 npm registry 上是不相干的套件。這一行不是 UDS 寫入的原樣，所以沒有動它。請自行改成 universal-dev-standards check——需要在本專案或 PATH 上已安裝 UDS CLI。',
+        hookMigrateFailed: '⚠ 無法改寫 .husky/pre-commit：{error}。請 npm 解析裸名稱 uds 的那一行仍在，請自行改成 universal-dev-standards check。',
         newerVersion: '（你的版本比登錄庫更新：{version}）',
         updateAvailable: '有可用更新：{current} → {latest}',
         // Files
@@ -2518,7 +2538,11 @@ export const messages = {
         uninstallPartial: '⚠ 解除安裝完成但有錯誤。',
         removed: '已移除',
         skippedLabel: '已跳過',
-        errorsLabel: '錯誤'
+        errorsLabel: '錯誤',
+        cannotPrompt: '無法詢問確認：目前沒有可回答提示的終端機（非互動 shell、CI 或管線）。',
+        cannotPromptHint: '尚未變更任何檔案。請加上 --yes 事先確認，或加上 --dry-run 預覽變更。',
+        promptClosed: '提示在回答前被關閉。尚未變更任何檔案。',
+        promptClosedMidRun: '執行途中提示被關閉。已完成的步驟維持完成；請再執行一次 `uds uninstall` 完成其餘部分。'
       }
     }
   },
@@ -3158,6 +3182,7 @@ export const messages = {
         title: '通用开发标准 - 初始化',
         alreadyInitialized: '⚠ 此项目已初始化标准。',
         useUpdateOrDelete: '使用 `uds update` 更新，或删除 .standards/ 重新初始化。',
+        useUpdateWithHooks: '要为这个项目补装执行关卡（含 UDS 在你初始化之后才支持的工具），请执行 `uds update --with-hooks`。',
         // Detection
         detectingProject: '正在检测项目特性...',
         analysisComplete: '项目分析完成',
@@ -3404,7 +3429,7 @@ export const messages = {
         missingSkillsHint: '提示：执行 `uds update` 安装缺少的 Skills/斜线命令',
         // 提交前检查是否真的会被 git 执行（uds init 写了检查文件，却没确认 git 会跑它——这里只回报，不写入）
         hookNotWiredTitle: '⚠ [pre-commit] {file} 已安装，但 git 实际不会执行它。',
-        hookNotWiredOverride: '  git core.hooksPath 已设定为“{path}”——UDS 不会覆盖它。请确认该路径下的文件也会执行 `npx uds check`，或自行改用：git config --local core.hooksPath .husky',
+        hookNotWiredOverride: '  git core.hooksPath 已设定为“{path}”——UDS 不会覆盖它。请确认该路径下的文件也会执行 `universal-dev-standards check`（要用已安装的 CLI——不要用短名称 uds，它在 npm registry 上是不相干的包），或自行改用：git config --local core.hooksPath .husky',
         hookNotWiredUnwired: '  git core.hooksPath 未设定，而 {file} 也不在 git 默认会读取的路径上。',
         hookNotWiredFix: '  修复方式（仅对此 clone 生效，不会进版控，其他人 clone 后要自己再跑一次）：git config --local core.hooksPath .husky',
         hookNotWiredFixNative: '  修复方式：把 core.hooksPath 改回默认（git config --local --unset core.hooksPath），或改在“{path}”下也加上 `uds check`。',
@@ -3416,6 +3441,8 @@ export const messages = {
         // 2026-09-27 于 CI（windows-latest）实测。
         hookMissingShebangTitle: '⚠ [pre-commit] {file} 没有 shebang 行——在 Windows 上 git 无法执行它。',
         hookMissingShebangFix: '  修复方式：在 {file} 的第一行加上 shebang `#!/bin/sh`（由 husky 管理的 hook，下次 `uds init` 动到它时会自动处理），或重新运行 `uds init`。',
+        hookBareUdsTitle: '⚠ [pre-commit] {file} 会请 npm 执行裸名称 uds，而它在 npm registry 上是不相干的包（不是本项目）。',
+        hookBareUdsFix: '  修复方式：运行 `uds update`——它会把 UDS 自己写入的那一行换成只执行已安装 UDS CLI 的写法。你自己写或改过的那一行不会被动，请自行改成 `universal-dev-standards check`。',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS 状态摘要',
@@ -3471,6 +3498,11 @@ export const messages = {
         currentVersion: '当前版本',
         latestVersion: '最新版本',
         upToDate: '✓ 标准是最新的。',
+        // pre-commit hook 迁移（npm registry 上的裸名称 uds 不是本项目）
+        hookMigrated: '✓ .husky/pre-commit：已把旧版 UDS 写入的那一行（它会请 npm 解析裸名称 uds，而那不是本项目）换成只执行已安装 UDS CLI 的写法。',
+        hookWouldMigrate: '+ .husky/pre-commit：将把旧版 UDS 写入的那一行（它会请 npm 解析裸名称 uds，而那不是本项目）换成只执行已安装 UDS CLI 的写法。',
+        hookLegacyKept: '⚠ .husky/pre-commit 第 {line} 行（“{text}”）会请 npm 解析裸名称 uds，而它在 npm registry 上是不相干的包。这一行不是 UDS 写入的原样，所以没有动它。请自行改成 universal-dev-standards check——需要在本项目或 PATH 上已安装 UDS CLI。',
+        hookMigrateFailed: '⚠ 无法改写 .husky/pre-commit：{error}。请 npm 解析裸名称 uds 的那一行仍在，请自行改成 universal-dev-standards check。',
         newerVersion: '（您有比注册表更新的版本：{version}）',
         updateAvailable: '有可用更新：{current} → {latest}',
         // Files
@@ -3697,7 +3729,11 @@ export const messages = {
         uninstallPartial: '⚠ 卸载完成但有错误。',
         removed: '已移除',
         skippedLabel: '已跳过',
-        errorsLabel: '错误'
+        errorsLabel: '错误',
+        cannotPrompt: '无法询问确认：当前没有可回答提示的终端（非交互 shell、CI 或管道）。',
+        cannotPromptHint: '尚未更改任何文件。请加上 --yes 提前确认，或加上 --dry-run 预览变更。',
+        promptClosed: '提示在回答前被关闭。尚未更改任何文件。',
+        promptClosedMidRun: '执行途中提示被关闭。已完成的步骤保持完成；请再运行一次 `uds uninstall` 完成其余部分。'
       }
     }
   }

package/src/installers/hooks-installer.js

@@ -31,11 +31,13 @@
  * @see core/turn-completion-integrity.md
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync } from 'fs';
-import { join, dirname, basename } from 'path';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, readdirSync } from 'fs';
+import { join, dirname, basename, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { execFileSync } from 'child_process';
 import { load as parseYaml } from 'js-yaml';
+import { detectAITools } from '../utils/detector.js';
+import { newRecorder, mkdirTracked, recordFile, RECORD_KINDS } from '../core/install-records.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -171,7 +173,41 @@ function probeLanguageLimits(hooksDir, scripts) {
   return out;
 }
 
-export function installHooks(projectPath) {
+/**
+ * Copy the shipped hook scripts (recursively — a hook may ship a directory beside
+ * it: locale packs, fixtures) into `<project>/scripts/hooks`, and RECORD every
+ * file this call actually wrote and every directory it had to create.
+ *
+ * `cpSync` did the copy before and returns nothing, which is why `uds uninstall`
+ * had no way to know which of the files under `scripts/hooks/` were UDS's — a
+ * directory an adopter's own hook scripts may share. A file that already exists
+ * and is byte-identical is not recorded (this call did not write it, so it
+ * proves nothing about who did); a file that exists, differs, and is not
+ * overwritten is left alone and not recorded.
+ *
+ * @param {string} srcDir  Shipped hooks directory
+ * @param {string} destDir Destination directory (absolute)
+ * @param {{ overwrite: boolean, recorder: object, projectPath: string }} ctx
+ */
+function copyTreeRecorded(srcDir, destDir, ctx) {
+  mkdirTracked(ctx.recorder, ctx.projectPath, destDir);
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const src = join(srcDir, entry.name);
+    const dest = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTreeRecorded(src, dest, ctx);
+      continue;
+    }
+    if (existsSync(dest)) {
+      if (!ctx.overwrite) continue;
+      if (readFileSync(src).equals(readFileSync(dest))) continue;
+    }
+    copyFileSync(src, dest);
+    recordFile(ctx.recorder, ctx.projectPath, relative(ctx.projectPath, dest), RECORD_KINDS.HOOK_SCRIPT);
+  }
+}
+
+export function installHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const claudeDir = join(projectPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.json');
   const hooksDir = join(projectPath, 'scripts', 'hooks');
@@ -186,11 +222,8 @@ export function installHooks(projectPath) {
     return { installed: false, scriptsCount: 0, settingsPath, events, skipped };
   }
 
-  if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
-  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
-
-  // Recursive: a hook may ship a directory beside it (locale packs, fixtures).
-  cpSync(hookDir, hooksDir, { recursive: true });
+  mkdirTracked(recorder, projectPath, claudeDir);
+  copyTreeRecorded(hookDir, hooksDir, { overwrite: overwriteScripts, recorder, projectPath });
 
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -216,6 +249,7 @@ export function installHooks(projectPath) {
     events,
     skipped,
     languageLimits: probeLanguageLimits(hooksDir, scripts),
+    artifacts: recorder,
   };
 }
 
@@ -258,10 +292,13 @@ export const AGY_HOOK_COMMAND = `node ../scripts/hooks/${AGY_HOOK_SCRIPT}`;
 // re-install repairs it and uninstall still removes it.
 export const AGY_HOOK_COMMAND_LEGACY = `node scripts/hooks/${AGY_HOOK_SCRIPT}`;
 
-/** Copy the shared hook scripts into the project, same as installHooks() does. */
-function copyHookScripts(hookDir, hooksDir) {
-  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
-  cpSync(hookDir, hooksDir, { recursive: true });
+/**
+ * Copy the shared hook scripts into the project, same as installHooks() does.
+ * `overwrite: false` keeps a script that already exists (an adopter may have
+ * edited it); it is what `uds update --with-hooks` uses unless `--force` is given.
+ */
+function copyHookScripts(hookDir, hooksDir, { overwrite = true, recorder, projectPath } = {}) {
+  copyTreeRecorded(hookDir, hooksDir, { overwrite, recorder, projectPath });
 }
 
 /**
@@ -278,7 +315,7 @@ function copyHookScripts(hookDir, hooksDir) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installCodexHooks(projectPath) {
+export function installCodexHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const hooksJsonPath = join(projectPath, '.codex', 'hooks.json');
   const hookDir = hooksSourceDir();
 
@@ -286,9 +323,8 @@ export function installCodexHooks(projectPath) {
     return { installed: false, settingsPath: hooksJsonPath, reason: `hook script not found: ${CODEX_HOOK_SCRIPT}` };
   }
 
-  const codexDir = join(projectPath, '.codex');
-  if (!existsSync(codexDir)) mkdirSync(codexDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'));
+  mkdirTracked(recorder, projectPath, join(projectPath, '.codex'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts, recorder, projectPath });
 
   let config = {};
   if (existsSync(hooksJsonPath)) {
@@ -305,7 +341,7 @@ export function installCodexHooks(projectPath) {
   ]);
 
   writeFileSync(hooksJsonPath, JSON.stringify(config, null, 2) + '\n');
-  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop' };
+  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop', artifacts: recorder };
 }
 
 /**
@@ -318,7 +354,7 @@ export function installCodexHooks(projectPath) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installGeminiHooks(projectPath) {
+export function installGeminiHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const settingsPath = join(projectPath, '.gemini', 'settings.json');
   const hookDir = hooksSourceDir();
 
@@ -326,9 +362,8 @@ export function installGeminiHooks(projectPath) {
     return { installed: false, settingsPath, reason: `hook script not found: ${GEMINI_HOOK_SCRIPT}` };
   }
 
-  const geminiDir = join(projectPath, '.gemini');
-  if (!existsSync(geminiDir)) mkdirSync(geminiDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'));
+  mkdirTracked(recorder, projectPath, join(projectPath, '.gemini'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts, recorder, projectPath });
 
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -344,7 +379,7 @@ export function installGeminiHooks(projectPath) {
   ]);
 
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-  return { installed: true, settingsPath, event: 'AfterAgent' };
+  return { installed: true, settingsPath, event: 'AfterAgent', artifacts: recorder };
 }
 
 /**
@@ -372,7 +407,7 @@ export function installGeminiHooks(projectPath) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installAgyHooks(projectPath) {
+export function installAgyHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const hooksJsonPath = join(projectPath, '.agents', 'hooks.json');
   const hookDir = hooksSourceDir();
 
@@ -392,9 +427,8 @@ export function installAgyHooks(projectPath) {
     }
   }
 
-  const agentsDir = join(projectPath, '.agents');
-  if (!existsSync(agentsDir)) mkdirSync(agentsDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'));
+  mkdirTracked(recorder, projectPath, join(projectPath, '.agents'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts, recorder, projectPath });
 
   const command = AGY_HOOK_COMMAND;
   const entry = config[AGY_HOOK_NAME];
@@ -411,5 +445,180 @@ export function installAgyHooks(projectPath) {
   config[AGY_HOOK_NAME] = { ...mine, Stop: stop };
 
   writeFileSync(hooksJsonPath, JSON.stringify(config, null, 2) + '\n');
-  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop' };
+  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop', artifacts: recorder };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `uds update --with-hooks` — hooks for a project that is already initialized.
+//
+// 🔴 Found 2026-09-29 installing the 6.14.0-beta.1 package into a fresh project:
+// hooks were only ever wired by `uds init --with-hooks`, and `uds init` refuses to
+// run twice ("Standards already initialized"). `uds update` had no hook option.
+// So an existing adopter could NEVER receive the hook for a tool UDS started
+// supporting after they initialized — and could not repair a hook file that was
+// never written. This is that door.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The tools that have a hook installer, in the order they are reported. */
+export const HOOK_CAPABLE_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'antigravity'];
+
+/** detectAITools() keys are camelCase; manifests and flags use the kebab-case tool names. */
+const DETECTED_KEY_TO_TOOL = { claudeCode: 'claude-code', geminiCli: 'gemini-cli' };
+
+/**
+ * Which tools to install hooks for.
+ *
+ *   --ai-tool given → exactly those (validated); nothing is detected or guessed.
+ *   otherwise       → the manifest's tools ∪ what the project directory shows now.
+ *
+ * The union is the point: a project initialized before agy detection existed (or
+ * before the adopter started using agy) has no `antigravity` in its manifest, and
+ * detection alone finds it; a project whose marker files were deleted still has
+ * the tool in its manifest. Either source is enough, neither is required.
+ *
+ * @param {string} projectPath
+ * @param {object|null} manifest
+ * @param {{ aiTool?: string }} [options]
+ * @returns {{ tools: string[], explicit: boolean, unknown: string[], sources: Record<string,string[]> }}
+ */
+export function resolveHookTools(projectPath, manifest, options = {}) {
+  if (options.aiTool) {
+    const asked = String(options.aiTool).split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
+    const unknown = asked.filter((t) => !HOOK_CAPABLE_TOOLS.includes(t));
+    const tools = HOOK_CAPABLE_TOOLS.filter((t) => asked.includes(t));
+    return { tools, explicit: true, unknown, sources: Object.fromEntries(tools.map((t) => [t, ['--ai-tool']])) };
+  }
+  const sources = {};
+  const add = (tool, why) => {
+    if (!HOOK_CAPABLE_TOOLS.includes(tool)) return;
+    (sources[tool] ||= []).push(why);
+  };
+  for (const t of [...(manifest?.integrations ?? []), ...(manifest?.aiTools ?? [])]) add(t, 'manifest');
+  const detected = detectAITools(projectPath);
+  for (const [k, on] of Object.entries(detected)) if (on) add(DETECTED_KEY_TO_TOOL[k] ?? k, 'detected in the project');
+  for (const t of Object.keys(sources)) sources[t] = [...new Set(sources[t])];
+  return { tools: HOOK_CAPABLE_TOOLS.filter((t) => sources[t]), explicit: false, unknown: [], sources };
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return { state: 'absent' };
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return { state: 'invalid', why: 'is not a JSON object' };
+    return { state: 'ok', value };
+  } catch {
+    return { state: 'invalid', why: 'is not valid JSON' };
+  }
+}
+
+const hasCommand = (entries, cmd) =>
+  Array.isArray(entries) && entries.some((e) => commandOf(e) === cmd);
+
+/**
+ * Is the hook for `tool` already in the project's config? Read-only.
+ *
+ * @returns {{ status: 'present'|'missing'|'stale'|'blocked', path: string, why?: string }}
+ *   present  every entry UDS would write is there — nothing to do
+ *   missing  none (or only part) of it is there
+ *   stale    agy's pre-fix command is there (does not resolve from agy's cwd)
+ *   blocked  the config file exists but cannot be merged safely (invalid JSON)
+ */
+export function hookStatus(projectPath, tool) {
+  if (tool === 'antigravity') {
+    const path = join(projectPath, '.agents', 'hooks.json');
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'blocked', path, why: `.agents/hooks.json ${j.why}; left untouched` };
+    const stop = j.value[AGY_HOOK_NAME]?.Stop;
+    const cmds = Array.isArray(stop) ? stop.map((h) => h && h.command) : [];
+    if (cmds.includes(AGY_HOOK_COMMAND) && !cmds.includes(AGY_HOOK_COMMAND_LEGACY)) return { status: 'present', path };
+    return { status: cmds.includes(AGY_HOOK_COMMAND_LEGACY) ? 'stale' : 'missing', path };
+  }
+  if (tool === 'codex') {
+    const path = join(projectPath, '.codex', 'hooks.json');
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'missing', path, why: 'unreadable; it would be rewritten by the installer' };
+    return { status: hasCommand(j.value.hooks?.Stop, `node scripts/hooks/${CODEX_HOOK_SCRIPT}`) ? 'present' : 'missing', path };
+  }
+  if (tool === 'gemini-cli') {
+    const path = join(projectPath, '.gemini', 'settings.json');
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'missing', path, why: 'unreadable; it would be rewritten by the installer' };
+    return { status: hasCommand(j.value.hooks?.AfterAgent, `node scripts/hooks/${GEMINI_HOOK_SCRIPT}`) ? 'present' : 'missing', path };
+  }
+  if (tool === 'claude-code') {
+    const path = join(projectPath, '.claude', 'settings.json');
+    const { configs } = collectHookConfigs(standardsSourceDir(), hooksSourceDir());
+    if (Object.keys(configs).length === 0) return { status: 'blocked', path, why: 'no standard produced a usable hook' };
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'missing', path, why: 'unreadable; it would be rewritten by the installer' };
+    for (const [event, entries] of Object.entries(configs)) {
+      const existing = j.value.hooks?.[event] ?? [];
+      if (mergeHookArray(existing, entries).length !== existing.length) return { status: 'missing', path };
+    }
+    return { status: 'present', path };
+  }
+  return { status: 'blocked', path: '', why: `no hook installer for ${tool}` };
+}
+
+/** Hook scripts UDS ships vs what the project already has: how many are new, identical, or edited. */
+function scriptDiff(projectPath) {
+  const src = hooksSourceDir();
+  const out = { added: 0, identical: 0, kept: [] };
+  if (!src) return out;
+  const walk = (dir, rel = '') => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { walk(join(dir, e.name), r); continue; }
+      const dest = join(projectPath, 'scripts', 'hooks', r);
+      if (!existsSync(dest)) out.added++;
+      else if (readFileSync(dest).equals(readFileSync(join(dir, e.name)))) out.identical++;
+      else out.kept.push(r);
+    }
+  };
+  walk(src);
+  return out;
+}
+
+const INSTALLERS = {
+  'claude-code': (p, o) => installHooks(p, o),
+  codex: (p, o) => installCodexHooks(p, o),
+  'gemini-cli': (p, o) => installGeminiHooks(p, o),
+  antigravity: (p, o) => installAgyHooks(p, o),
+};
+
+/**
+ * Add the hooks that are missing to an already-initialized project.
+ *
+ * - A hook that is already there is not touched, and nothing is written for it.
+ * - The adopter's own hooks are never touched: every installer merges (Claude,
+ *   Codex, Gemini) or writes only under the key UDS owns (agy).
+ * - A hook script the project already has and that differs from this version is
+ *   KEPT unless `overwriteScripts` — it may have been edited. It is reported.
+ * - `plan: true` reads and reports, and writes nothing.
+ *
+ * @param {string} projectPath
+ * @param {string[]} tools
+ * @param {{ plan?: boolean, overwriteScripts?: boolean }} [opts]
+ * @returns {{ results: Array<{tool:string, outcome:'installed'|'unchanged'|'would-install'|'blocked'|'failed', path:string, why?:string, repaired?:boolean}>, scripts: {added:number, identical:number, kept:string[]}, artifacts: object }}
+ *   `artifacts` is the recorder of what this call wrote (see core/install-records.js);
+ *   the caller persists it into the manifest so `uds uninstall` can remove exactly that.
+ */
+export function installMissingHooks(projectPath, tools, { plan = false, overwriteScripts = false, recorder = newRecorder() } = {}) {
+  // Measured BEFORE anything is copied: afterwards every script would read "identical".
+  const scripts = scriptDiff(projectPath);
+  const results = [];
+  for (const tool of tools) {
+    const st = hookStatus(projectPath, tool);
+    if (st.status === 'present') { results.push({ tool, outcome: 'unchanged', path: st.path }); continue; }
+    if (st.status === 'blocked') { results.push({ tool, outcome: 'blocked', path: st.path, why: st.why }); continue; }
+    if (plan) { results.push({ tool, outcome: 'would-install', path: st.path, repaired: st.status === 'stale' }); continue; }
+    const r = INSTALLERS[tool](projectPath, { overwriteScripts, recorder });
+    if (r.installed) results.push({ tool, outcome: 'installed', path: r.settingsPath ?? st.path, repaired: st.status === 'stale' });
+    else results.push({ tool, outcome: 'failed', path: r.settingsPath ?? st.path, why: r.reason ?? 'no standard produced a usable hook' });
+  }
+  return { results, scripts, artifacts: recorder };
 }

package/src/installers/integration-installer.js

@@ -141,6 +141,10 @@ export async function installIntegrations(config, projectPath) {
     if (result.success) {
       results.integrations.push(result.path);
       generatedFiles.add(targetFile);
+      // Files this run created from nothing (not merged into an existing file);
+      // init records them so uninstall can prove they are wholly UDS's. Added only
+      // when there is one, so an empty run keeps its original result shape.
+      if (result.created) (results.createdFiles ||= []).push(result.path);
 
       // Capture integration block hash for tracking UDS content
       if (result.blockHashInfo) {
@@ -310,7 +314,7 @@ export async function generateUniversalAgentsMd(config, integrationResults, proj
 
   if (result.success) {
     spinner.succeed(msg.generatedAgentsMd || 'Generated AGENTS.md (universal summary)');
-    return { path: result.path, error: null, blockHashInfo: result.blockHashInfo };
+    return { path: result.path, error: null, blockHashInfo: result.blockHashInfo, created: result.created };
   } else {
     spinner.warn(msg.couldNotGenerateAgentsMd || 'Could not generate AGENTS.md');
     return { path: null, error: result.error };