universal-dev-standards 6.13.0-beta.1 → 6.13.0-beta.4

package/src/commands/check.js

@@ -45,6 +45,7 @@ import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { lintAll as lintI18nAll, partitionFindings as partitionI18nFindings } from '../lint/i18n.js';
 import { resolveIntegrationFile } from '../core/constants.js';
+import { checkPreCommitHookWiring } from '../utils/git-hooks.js';
 
 /**
  * Display the summary of file integrity status
@@ -509,6 +510,9 @@ export async function checkCommand(options = {}) {
   // 錯誤訊息單一出口閘門是否已安裝（只報告，不寫入）
   checkErrorExitGate(projectPath);
 
+  // pre-commit 檢查檔存在，但 git 實際不會執行它（只報告，不寫入 —— 見 checkPreCommitWiring 下方註解）
+  checkPreCommitWiring(projectPath, msg);
+
   // Workflow status
   displayWorkflowStatus(projectPath);
 
@@ -1252,6 +1256,81 @@ function checkErrorExitGate(projectPath) {
   console.log();
 }
 
+/**
+ * pre-commit 檢查檔存在，但 git 實際不會執行它：偵測並報告，絕不寫入。
+ *
+ * 🔴 起因：`uds init` 會寫 `.husky/pre-commit`（或非 Node 專案的
+ * `.git/hooks/pre-commit`），但過去從未確認 git 真的會執行它——它依賴 husky
+ * 自己的 bootstrap（`npm install` 觸發 `prepare` script 設定
+ * `core.hooksPath`），而那個時機點如果 `node_modules` 已存在就永遠不會再發生。
+ * 2026-09-26 實測三個既有採用者（asiaostrich-telemetry-server、
+ * asiaostrich-telemetry-client、machine-setup）：三者都有呼叫
+ * `npx uds check` 的 `.husky/pre-commit`，但 `core.hooksPath` 皆未設定，
+ * 提交時檢查從未跑過，且沒有任何錯誤訊息——這正是這道檢查要補上的訊號。
+ *
+ * 只報告不寫入的理由與 checkErrorExitGate 相同：`uds check` 不是使用者同意我們
+ * 動他 git 設定的時刻；真要修，`uds init`（新 clone／尚未跑過）或使用者自己
+ * 手動下指令（既有 clone）才是合適的落筆點。
+ *
+ * 🔴 刻意不影響 `allGood` / `--ci` 的 exit code：這是一個既有裝置的健康度警告
+ * （類似 checkErrorExitGate、checkFullCoverageCompliance 的既有慣例），不是
+ * 標準本身的落差，翻動 exit code 會讓不相關的 CI pipeline 因為一個提交前檢查
+ * 的本機設定而失敗，而那個設定本來就是 per-clone、CI 環境通常另有一套。
+ */
+export function checkPreCommitWiring(projectPath, msg) {
+  const result = checkPreCommitHookWiring(projectPath);
+  if (!result.relevant) return; // 沒有 UDS 管理的 hook
+
+  if (result.wired) {
+    // 🔴 「已確認會執行」在 POSIX 上為真，在 Windows 上不一定——git for
+    // Windows 沒有 POSIX 的 ENOEXEC → /bin/sh 後備機制，缺 shebang 的 hook
+    // 每次 commit 都會失敗，訊息卻指向 hook 檔本身
+    // （`cannot spawn <file>: No such file or directory`），2026-09-27 實測
+    // 於 CI windows-latest。這與「wiring」是兩個獨立的缺陷面，有各自的旗標。
+    if (result.missingShebang) {
+      console.log(chalk.yellow((msg.hookMissingShebangTitle || '⚠ [pre-commit] {file} has no shebang line — git cannot run it on Windows.')
+        .replace('{file}', result.hookFile)));
+      console.log(chalk.gray((msg.hookMissingShebangFix || '').replace(/\{file\}/g, result.hookFile)));
+      console.log();
+    }
+    return; // 已確認會執行——wiring 本身安靜通過
+  }
+
+  console.log(chalk.yellow((msg.hookNotWiredTitle || '⚠ [pre-commit] {file} was installed, but git will not run it.')
+    .replace('{file}', result.hookFile)));
+
+  if (result.configuredHooksPath) {
+    const key = result.hookFile === '.git/hooks/pre-commit' ? 'hookNotWiredFixNative' : 'hookNotWiredOverride';
+    console.log(chalk.gray((msg[key] || '').replace('{path}', result.configuredHooksPath)));
+    // 🔴 legacy 舊範本即使在 override 分支也要提醒——一旦使用者照上面那行改用
+    // .husky，同一個 `_/husky.sh` 陷阱一樣會炸。絕不能只在「非 override」分支講。
+    if (result.legacyV8) {
+      console.log(chalk.gray((msg.hookNotWiredLegacyV8Fix || '').replace(/\{file\}/g, result.hookFile)));
+    }
+  } else if (result.legacyV8) {
+    // 🔴 這是 2026-09-27 的實測教訓：舊 husky v8 範本（含 `_/husky.sh` source
+    // 那一行）若只給「設定 core.hooksPath」這個修法，使用者照做後 git 會直接
+    // 執行這個檔案、卡死在那一行、每次 commit 都失敗——比原本的缺陷更糟。
+    // 這裡絕不能退化成只印 hookNotWiredFix；一定要用把「先刪行、再設定」
+    // 兩步講完整的版本。`uds init` 對已初始化專案會直接拒絕執行，修不了這個，
+    // 所以這裡的文字必須自己講完整，不能叫使用者去跑別的指令。
+    console.log(chalk.gray((msg.hookNotWiredFixLegacy || '').replace(/\{file\}/g, result.hookFile)));
+  } else {
+    console.log(chalk.gray((msg.hookNotWiredUnwired || '').replace('{file}', result.hookFile)));
+    console.log(chalk.gray(msg.hookNotWiredFix || ''));
+  }
+
+  // Independent of wiring — a hook can be fully wired for commit and still
+  // fail every commit on Windows if it has no shebang (see the `wired`
+  // branch above for why). Say so here too so fixing wiring alone does not
+  // look like a complete fix.
+  if (result.missingShebang) {
+    console.log(chalk.gray((msg.hookMissingShebangFix || '').replace(/\{file\}/g, result.hookFile)));
+  }
+
+  console.log();
+}
+
 /**
  * XSPEC-178: Check full-coverage-testing standard presence and STUB markers
  */

package/src/commands/init.js

@@ -28,6 +28,7 @@ import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { readInstallYaml } from '../utils/config-manager.js';
 import { resolveIntegrationTargetFile } from '../utils/integration-generator.js';
 import { withFileTransaction } from '../utils/transaction.js';
+import { wireGitHooksPath, getLocalHooksPathConfig, stripLegacyHuskyShLine, ensureShebang } from '../utils/git-hooks.js';
 
 /**
  * Init command - initialize standards in current project
@@ -339,32 +340,42 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
   const isNodeProject = existsSync(join(projectPath, 'package.json'));
 
   if (isNodeProject) {
-    console.log(chalk.cyan('Configuring Pre-commit Hook (Husky)...'));
+    console.log(chalk.cyan('Configuring Pre-commit Hook...'));
 
     // Every edit we make to the adopter's package.json, reported at the end.
     // `uds init` writes ~70 files; a one-line change to package.json is invisible
     // in that diff unless we say it out loud (XSPEC-341 R1).
     const pkgChanges = [];
+    const pkgPath = join(projectPath, 'package.json');
 
-    // 1. Install husky if needed
+    // 1. Do NOT install husky, and do NOT touch package.json's dependencies.
+    //
+    // This used to run `npm install --save-dev husky` here. Installing a
+    // package for the adopter is not this command's call to make, and — the
+    // actual bug this fix addresses — the wiring that install produced only
+    // took effect the NEXT time `npm install` ran husky's own `prepare`
+    // script. If node_modules already existed, that install never ran again,
+    // and the hook this function writes below was never executed by git.
+    // Verified against three real adopters (asiaostrich-telemetry-server,
+    // asiaostrich-telemetry-client, machine-setup, 2026-09-26): all three
+    // have `.husky/pre-commit` calling `npx uds check`, none has
+    // `core.hooksPath` set, and the check has never once run on commit.
+    //
+    // Whether husky is installed is the adopter's own decision. Step 5 below
+    // wires git directly and works with or without it.
+    let hasHusky = false;
     try {
-      const pkgPath = join(projectPath, 'package.json');
       const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-      const hasHusky = pkg.devDependencies?.husky || pkg.dependencies?.husky;
-
-      if (!hasHusky) {
-        console.log(chalk.gray('  Installing husky...'));
-        // stdio: 'pipe' rather than 'ignore' — the error text belongs in the
-        // message below, not in /dev/null.
-        execSync('npm install --save-dev husky', { stdio: 'pipe', cwd: projectPath });
-        pkgChanges.push('devDependencies.husky — added');
-      }
+      hasHusky = Boolean(pkg.devDependencies?.husky || pkg.dependencies?.husky);
     } catch (e) {
-      console.log(chalk.yellow(`  ⚠ Failed to check/install husky: ${e.message}`));
-      return;
+      console.log(chalk.yellow(`  ⚠ Failed to read package.json: ${e.message}`));
     }
 
-    // 2. Wire husky's `prepare` script ourselves.
+    // 2. If the adopter already depends on husky, also chain its `prepare`
+    // script so a future `npm install` keeps husky's own wiring in sync too.
+    // This is belt-and-suspenders — step 5 wires git directly regardless of
+    // whether this succeeds — kept only because an adopter who already uses
+    // husky should not have `npm install` silently stop maintaining it.
     //
     // We deliberately do NOT run `npx husky init` (XSPEC-341 R1). That command is a
     // one-time bootstrap for a NEW project, not an idempotent operation: it sets
@@ -375,30 +386,31 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
     // (It also seeds .husky/pre-commit with `npm test`, a gate the adopter never asked
     // for.) Adopting a standards library must never rewrite the adopter's build.
     const huskyDir = join(projectPath, '.husky');
-    try {
-      const pkgPath = join(projectPath, 'package.json');
-      const raw = readFileSync(pkgPath, 'utf-8');
-      const pkg = JSON.parse(raw);
-      pkg.scripts = pkg.scripts || {};
-      const existing = pkg.scripts.prepare;
-
-      if (!existing) {
-        pkg.scripts.prepare = 'husky';
-        pkgChanges.push('scripts.prepare — added: "husky"');
-      } else if (!/\bhusky\b/.test(existing)) {
-        // Chain, never clobber. The adopter's command runs first and keeps its
-        // exit code meaningful.
-        pkg.scripts.prepare = `${existing} && husky`;
-        pkgChanges.push(`scripts.prepare — "${existing}" → "${pkg.scripts.prepare}"`);
-      }
+    if (hasHusky) {
+      try {
+        const raw = readFileSync(pkgPath, 'utf-8');
+        const pkg = JSON.parse(raw);
+        pkg.scripts = pkg.scripts || {};
+        const existing = pkg.scripts.prepare;
+
+        if (!existing) {
+          pkg.scripts.prepare = 'husky';
+          pkgChanges.push('scripts.prepare — added: "husky"');
+        } else if (!/\bhusky\b/.test(existing)) {
+          // Chain, never clobber. The adopter's command runs first and keeps its
+          // exit code meaningful.
+          pkg.scripts.prepare = `${existing} && husky`;
+          pkgChanges.push(`scripts.prepare — "${existing}" → "${pkg.scripts.prepare}"`);
+        }
 
-      if (pkg.scripts.prepare !== existing) {
-        // Preserve the file's trailing newline convention.
-        const indent = raw.match(/^\{\n(\s+)"/)?.[1]?.length ?? 2;
-        writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : ''), 'utf-8');
+        if (pkg.scripts.prepare !== existing) {
+          // Preserve the file's trailing newline convention.
+          const indent = raw.match(/^\{\n(\s+)"/)?.[1]?.length ?? 2;
+          writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : ''), 'utf-8');
+        }
+      } catch (e) {
+        console.log(chalk.yellow(`  ⚠ Failed to configure the prepare script: ${e.message}`));
       }
-    } catch (e) {
-      console.log(chalk.yellow(`  ⚠ Failed to configure the prepare script: ${e.message}`));
     }
 
     // 3. Ensure .husky directory exists
@@ -411,34 +423,97 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
       }
     }
 
-    // 4. Add pre-commit hook
+    // 4. Add pre-commit hook content
     const preCommitPath = join(huskyDir, 'pre-commit');
     const udsCmd = 'npx uds check';
 
     try {
-      // husky v9 hooks are plain shell scripts: no shebang, no `_/husky.sh` sourcing
-      // (that is v8 syntax, deprecated in v9 and removed in v10). We install husky
-      // ^9, so a fresh hook must be v9-shaped. Existing files are appended to, never
-      // rewritten — their contents are the adopter's, not ours.
-      const content = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : '';
-
-      if (!content.includes('uds check')) {
+      // husky v9's own templates carry no shebang, no `_/husky.sh` sourcing
+      // (that is v8 syntax, deprecated in v9 and removed in v10). Verified
+      // empirically (2026-09-26, macOS): git executes a hook file with no
+      // shebang directly and correctly propagates its exit code, once it is
+      // on git's hooks path — see step 5.
+      //
+      // 🔴 That verification did not cover Windows, and Windows behaves
+      // differently: POSIX git falls back to `/bin/sh` on ENOEXEC (a script
+      // with no shebang) — that fallback is why the shebang-less shape above
+      // has always worked on macOS and Linux. Git for Windows has no such
+      // fallback and fails EVERY commit with `error: cannot spawn
+      // <hookfile>: No such file or directory` (measured 2026-09-27 in CI,
+      // windows-latest). So a shebang is added below regardless of platform
+      // — cheap, harmless on POSIX, and required on Windows. Existing files
+      // are appended to, never rewritten — their contents are the adopter's,
+      // not ours; ensureShebang only ever prepends a missing first line.
+      let content = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : '';
+
+      // A pre-existing file may still carry husky v8's `_/husky.sh` sourcing
+      // line (adopted before v9, or before this fix). That line references a
+      // directory (`.husky/_/`) that only exists after husky's OWN bootstrap
+      // has run — but step 5 below wires `core.hooksPath` straight at
+      // `.husky`, so git executes THIS FILE directly. Left in place, that
+      // line would make every commit fail with "No such file or directory" —
+      // strictly worse than the original defect (verified against a real
+      // adopter's exact legacy template, 2026-09-27). Rewrite it away rather
+      // than appending alongside it; everything else — the adopter's own
+      // commands, an existing `uds check` line — is preserved as-is.
+      const { content: destripped, removed: hadLegacyLine } = stripLegacyHuskyShLine(content);
+      content = destripped;
+
+      const needsAppend = !content.includes('uds check');
+      if (needsAppend) {
         const sep = content && !content.endsWith('\n') ? '\n' : '';
-        writeFileSync(preCommitPath, `${content}${sep}\n# UDS Standard Check\n${udsCmd}\n`, 'utf-8');
+        content = `${content}${sep}\n# UDS Standard Check\n${udsCmd}\n`;
+      }
+
+      const { content: shebanged, added: addedShebang } = ensureShebang(content);
+      content = shebanged;
+
+      if (hadLegacyLine || needsAppend || addedShebang) {
+        writeFileSync(preCommitPath, content, 'utf-8');
         try {
           execSync(`chmod +x ${preCommitPath}`);
         } catch {
           // Ignore chmod failures on systems that don't support it
         }
+      }
+
+      if (hadLegacyLine) {
+        console.log(chalk.yellow('  ⚠ Rewrote legacy husky v8 template: removed `_/husky.sh` sourcing (that directory only exists after husky\'s own bootstrap runs; git now executes this file directly, so that line would have failed every commit).'));
+      }
+      if (addedShebang) {
+        console.log(chalk.yellow('  ⚠ Added a missing #!/bin/sh shebang: without it, git cannot execute this hook on Windows.'));
+      }
+      if (needsAppend) {
         console.log(chalk.green('  ✓ Adding uds check to pre-commit hook'));
-      } else {
+      } else if (!hadLegacyLine && !addedShebang) {
         console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
       }
     } catch (e) {
       console.log(chalk.red(`  ✗ Failed to configure pre-commit hook: ${e.message}`));
     }
 
-    // 5. Say what we changed in their package.json.
+    // 5. Wire git so the hook ACTUALLY runs — this is the fix. Setting
+    // `core.hooksPath` ourselves is what husky's own bootstrap does internally
+    // (verified against husky ^9.1.7's source: `git config core.hooksPath
+    // <dir>/_`, plus a shim under `_/` forwarding to the real script); doing
+    // it directly means the check is live immediately after `uds init`,
+    // whether or not husky is installed or `npm install` ever runs again.
+    // Never overrides an adopter's own `core.hooksPath`, or an existing
+    // native `.git/hooks/pre-commit` (see wireGitHooksPath).
+    const wireResult = wireGitHooksPath(projectPath, '.husky');
+    if (wireResult.wired) {
+      console.log(chalk.green('  ✓ Pre-commit check is active for this clone (git core.hooksPath → .husky)'));
+    } else {
+      console.log(chalk.yellow(`  ⚠ Pre-commit check NOT enabled: ${wireResult.reason}`));
+      console.log(chalk.gray(`    ${wireResult.hint}`));
+    }
+    // `core.hooksPath` is LOCAL git config — it is never committed. This wiring
+    // only applies to this clone; `uds check` reports the gap for anyone who
+    // clones the repo without re-running this step (see
+    // checkPreCommitHookWiring in git-hooks.js / check.js).
+    console.log(chalk.gray('    Note: this is per-clone (git config is not committed) — teammates need to run `uds init` (or the fix above) in their own clone too.'));
+
+    // 6. Say what we changed in their package.json.
     if (pkgChanges.length > 0) {
       console.log(chalk.cyan('  package.json modified:'));
       for (const change of pkgChanges) {
@@ -452,13 +527,34 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
     const hookDir = join(projectPath, '.git', 'hooks');
     const hookPath = join(hookDir, 'pre-commit');
 
+    // git's default hooks directory is `.git/hooks` — but only when
+    // `core.hooksPath` is unset. If the adopter (or another tool) already
+    // points it elsewhere, writing here would produce a file git never looks
+    // at, and `uds init` would report success for a check that never runs.
+    const configuredHooksPath = getLocalHooksPathConfig(projectPath);
+    if (configuredHooksPath) {
+      console.log(chalk.yellow(`  ⚠ Pre-commit check NOT enabled: git core.hooksPath is already set to "${configuredHooksPath}"`));
+      console.log(chalk.gray('    UDS writes to .git/hooks/pre-commit, but git will not look there while core.hooksPath points elsewhere.'));
+      console.log(chalk.gray(`    Add "uds check" to a pre-commit hook under "${configuredHooksPath}" yourself, or: git config --local --unset core.hooksPath`));
+      console.log();
+      return;
+    }
+
     try {
       if (!existsSync(hookDir)) {
         mkdirSync(hookDir, { recursive: true });
       }
 
-      if (existsSync(hookPath) && readFileSync(hookPath, 'utf-8').includes('uds check')) {
-        console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
+      if (existsSync(hookPath)) {
+        const existingContent = readFileSync(hookPath, 'utf-8');
+        if (existingContent.includes('uds check')) {
+          console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
+        } else {
+          // Never clobber an adopter's own hook (this fix — it used to be
+          // overwritten unconditionally here).
+          console.log(chalk.yellow('  ⚠ Pre-commit check NOT enabled: .git/hooks/pre-commit already exists'));
+          console.log(chalk.gray('    UDS will not overwrite it. Add "uds check" to it yourself, or remove it and re-run `uds init`.'));
+        }
       } else {
         const hookContent = `#!/bin/sh
 # UDS pre-commit hook

package/src/commands/uninstall.js

@@ -56,7 +56,7 @@ export async function uninstallCommand(options) {
     const categories = await checkbox({
       message: msg.selectCategories,
       choices: [
-        { name: `${msg.categoryHooks} (.husky/pre-commit)`, value: 'hooks', checked: true },
+        { name: `${msg.categoryHooks} (.husky/pre-commit, .claude/settings.json, .codex/hooks.json, .gemini/settings.json)`, value: 'hooks', checked: true },
         { name: `${msg.categorySkills} (skills, commands)`, value: 'skills', checked: true },
         { name: `${msg.categoryIntegrations} (CLAUDE.md, .cursorrules, ...)`, value: 'integrations', checked: true },
         { name: `${msg.categoryStandards} (.standards/)`, value: 'standards', checked: true }

package/src/i18n/messages.js

@@ -872,6 +872,26 @@ export const messages = {
         commandsInstalledSuccess: 'Installed commands for {count} AI tools',
         // Read-only hint
         missingSkillsHint: 'Tip: Run `uds update` to install missing Skills/Commands',
+        // 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',
+        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.',
+        // Order matters here: setting hooksPath BEFORE removing the `_/husky.sh`
+        // line makes git execute {file} directly and fail on that line — verified
+        // against a real adopter's exact legacy template, 2026-09-27. `uds init`
+        // will not fix this for an already-initialized project (it refuses to run
+        // at all once `.standards/` exists), so the fix must be self-contained here.
+        hookNotWiredFixLegacy: '  Fix, in this exact order — this file still sources `_/husky.sh` (husky v8 syntax), a directory that only exists after husky\'s own bootstrap has run: (1) delete the line `. "$(dirname -- "$0")/_/husky.sh"` from {file}; (2) then run: git config --local core.hooksPath .husky (per-clone — not committed, teammates must repeat it). Doing (2) alone makes every commit fail with an error that `_/husky.sh` cannot be found ("No such file or directory" on macOS, ".: cannot open" on Linux).',
+        hookNotWiredLegacyV8Fix: '  Also: {file} still sources `_/husky.sh` (husky v8 syntax) — delete that line too, or the fix above will make every commit fail with an error that `_/husky.sh` cannot be found ("No such file or directory" on macOS, ".: cannot open" on Linux).',
+        // Missing shebang: independent of wiring — POSIX git falls back to
+        // /bin/sh on ENOEXEC (a hook with no shebang), git for Windows does
+        // not, and fails every commit with "cannot spawn {file}: No such
+        // 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`.',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS Status Summary',
@@ -2112,6 +2132,24 @@ export const messages = {
         commandsInstalledSuccess: '已為 {count} 個 AI 工具安裝斜線命令',
         // Read-only hint
         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',
+        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`。',
+        // 順序不可顛倒：先設 hooksPath 再刪那一行，會讓 git 直接執行 {file} 並卡在
+        // `_/husky.sh` 那一行（2026-09-26 已在真實採用者的舊範本上實測到）。
+        // `uds init` 對已初始化的專案會直接拒絕執行，修不了這個，所以這裡要給
+        // 一次就講完整、不需要再跑任何指令的修法。
+        hookNotWiredFixLegacy: '  修復方式，順序不可顛倒——這個檔案還留著 `_/husky.sh`（husky v8 舊語法），它 source 的目錄只有在 husky 自己的 bootstrap 跑過後才存在：(1) 先刪掉 {file} 裡的這一行：`. "$(dirname -- "$0")/_/husky.sh"`；(2) 再執行：git config --local core.hooksPath .husky（僅對此 clone 生效，不會進版控，其他人要自己再做一次）。只做 (2) 不做 (1) 會讓每一次提交都失敗，印出找不到 `_/husky.sh` 的錯誤（macOS 為「No such file or directory」、Linux 為「.: cannot open」）。',
+        hookNotWiredLegacyV8Fix: '  另外：{file} 還留著 `_/husky.sh`（husky v8 舊語法）——這一行也要刪掉，不然上面的修復方式會讓每一次提交都失敗，印出找不到 `_/husky.sh` 的錯誤（macOS 為「No such file or directory」、Linux 為「.: cannot open」）。',
+        // 缺少 shebang：與 wiring 無關——POSIX git 在 ENOEXEC（hook 沒有 shebang）
+        // 時會退回用 /bin/sh 執行，git for Windows 沒有這個後備機制，每次提交
+        // 都會失敗，訊息是「cannot spawn {file}: No such file or directory」。
+        // 2026-09-27 於 CI（windows-latest）實測。
+        hookMissingShebangTitle: '⚠ [pre-commit] {file} 沒有 shebang 行——在 Windows 上 git 無法執行它。',
+        hookMissingShebangFix: '  修復方式：在 {file} 的第一行加上 shebang `#!/bin/sh`（由 husky 管理的 hook，下次 `uds init` 動到它時會自動處理），或重新執行 `uds init`。',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS 狀態摘要',
@@ -3364,6 +3402,20 @@ export const messages = {
         commandsInstalledSuccess: '已为 {count} 个 AI 工具安装斜线命令',
         // Read-only hint
         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',
+        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`。',
+        hookNotWiredFixLegacy: '  修复方式，顺序不可颠倒——这个文件还留着 `_/husky.sh`（husky v8 旧语法），它 source 的目录只有在 husky 自己的 bootstrap 跑过后才存在：(1) 先删掉 {file} 里的这一行：`. "$(dirname -- "$0")/_/husky.sh"`；(2) 再执行：git config --local core.hooksPath .husky（仅对此 clone 生效，不会进版控，其他人要自己再做一次）。只做 (2) 不做 (1) 会让每一次提交都失败，打印找不到 `_/husky.sh` 的错误（macOS 为“No such file or directory”、Linux 为“.: cannot open”）。',
+        hookNotWiredLegacyV8Fix: '  另外：{file} 还留着 `_/husky.sh`（husky v8 旧语法）——这一行也要删掉，不然上面的修复方式会让每一次提交都失败，打印找不到 `_/husky.sh` 的错误（macOS 为“No such file or directory”、Linux 为“.: cannot open”）。',
+        // 缺少 shebang：与 wiring 无关——POSIX git 在 ENOEXEC（hook 没有 shebang）
+        // 时会回退用 /bin/sh 执行，git for Windows 没有这个后备机制，每次提交
+        // 都会失败，消息是“cannot spawn {file}: No such file or directory”。
+        // 2026-09-27 于 CI（windows-latest）实测。
+        hookMissingShebangTitle: '⚠ [pre-commit] {file} 没有 shebang 行——在 Windows 上 git 无法执行它。',
+        hookMissingShebangFix: '  修复方式：在 {file} 的第一行加上 shebang `#!/bin/sh`（由 husky 管理的 hook，下次 `uds init` 动到它时会自动处理），或重新运行 `uds init`。',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS 状态摘要',

package/src/installers/hooks-installer.js

@@ -231,8 +231,12 @@ export function installHooks(projectPath) {
  *
  * @see core/turn-completion-integrity.md
  */
-const CODEX_HOOK_SCRIPT = 'check-turn-completion-codex.mjs';
-const GEMINI_HOOK_SCRIPT = 'check-turn-completion-gemini.mjs';
+// Exported so the uninstaller (../uninstallers/hook-uninstaller.js) can
+// recognize exactly these two script names as UDS's own, rather than
+// guessing from the shared `scripts/hooks/` directory path alone — a path
+// an adopter's own hook could just as easily live under.
+export const CODEX_HOOK_SCRIPT = 'check-turn-completion-codex.mjs';
+export const GEMINI_HOOK_SCRIPT = 'check-turn-completion-gemini.mjs';
 
 /** Copy the shared hook scripts into the project, same as installHooks() does. */
 function copyHookScripts(hookDir, hooksDir) {