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

package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md

@@ -886,6 +886,30 @@ UDS 的專案——並在 `[pre-commit]` 底下回報同樣的修復方式；此
 （已評估、不支援），見
 [支援的執行環境](../../../core/turn-completion-integrity.md#supported-harnesses)。
 
+### 為已初始化的專案補裝 Hooks（`uds update --with-hooks`）
+
+`uds init` 不能跑第二次，所以 `--with-hooks` 到不了已經初始化的專案——包括在 UDS 支援某個工具**之前**
+（或在偵測認得它之前）就初始化的專案。`uds update --with-hooks` 就是那扇門：
+
+```bash
+uds update --with-hooks --plan                   # 列出會裝什麼；不寫任何檔
+uds update --with-hooks                          # 補裝缺少的 hooks
+uds update --with-hooks --ai-tool antigravity    # 直接指定工具，不做偵測
+```
+
+- **裝給哪些工具。** `.standards/manifest.json` 裡的工具，加上專案檔案現在看得出來的（Claude Code：
+  `.claude/` 或 `CLAUDE.md`；Codex：根目錄 `AGENTS.md`；Gemini CLI：`GEMINI.md`；Antigravity：
+  `.agents/AGENTS.md`、`.agents/rules/`、`.agents/workflows/`、`.agents/plugins/` 或
+  `.agents/hooks.json`）。**`.agents/skills/` 不算 Antigravity 的標記**——Codex 也從同一個目錄讀專案技能，
+  所以它分不出是哪個工具。`--ai-tool <清單>`（`claude-code`、`codex`、`gemini-cli`、`antigravity`，
+  以逗號分隔）會取代偵測。找不到任何工具時，它會說明、印出如何指定，並以 1 結束。
+- **不會動什麼。** 已經裝好的 hook 不會被重寫。你自己的 hooks 不會被移除或重排：Claude、Codex、Gemini 的
+  項目是合併進去；Antigravity 的 `.agents/hooks.json` 只寫在 `uds-turn-completion-integrity` 這個鍵底下
+  （不是合法 JSON 的 `hooks.json` 會原樣保留並回報）。`scripts/hooks/` 裡與隨附版本不同的 hook 腳本會被保留並回報；
+  加上 `--force` 才會覆寫。
+- **它不做什麼。** 不更新標準、技能或整合檔（那是一般的 `uds update`），也不會把工具加進 manifest。
+  它不能與 `--skills`、`--commands` 等其他 update 模式合用，合用時會明說。
+
 ### Claude Code 整合目標檔（`--claude-target`）
 
 UDS 預設把 Claude Code 內容寫進 `CLAUDE.md`——團隊共用、會進版控的那個檔案。

package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md

@@ -9,15 +9,15 @@
 
 ## 目錄
 
-1. [CLI 指令](#cli-commands) (23)
+1. [CLI 指令](#cli-commands) (24)
 2. [斜線命令](#slash-commands) (51)
 3. [技能](#skills) (55)
 4. [代理](#agents) (5)
 5. [工作流程](#workflows) (5)
 6. [核心規範](#core-standards) (153)
-7. [腳本](#scripts) (62)
+7. [腳本](#scripts) (63)
 
-**Total Features: 354**
+**Total Features: 356**
 
 ---
 
@@ -158,6 +158,8 @@
 | `--rollback` | Rollback to the most recent backup |
 | `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
 | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
+| `--with-hooks` | Install the enforcement hooks that are missing from this already-initialized project (re-detects tools; hooks already there and your own hooks are not touched; with --plan, writes nothing; --force also overwrites edited hook scripts) |
+| `--ai-tool` | With --with-hooks: comma-separated tools to install hooks for (claude-code, codex, gemini-cli, antigravity) instead of detecting them |
 
 ### `uds skills`
 
@@ -276,6 +278,10 @@
 
 **說明**: MCP server commands for AI tool integration
 
+### `uds open-work`
+
+**說明**: Reference checks for open-work-tracking (OWT-017/018/019). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass)
+
 ### `uds run`
 
 **說明**: Run a project command by intent (test/lint/build/security) via uds.project.yaml
@@ -610,7 +616,8 @@
 | `check-docs-sync.sh` | Documentation Sync Checker |
 | `check-error-exit.mjs` | 🔴 沒填就是沒設定，而沒設定會 exit 2， |
 | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ-5, AC-7) |
-| `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 / OWT-018 / OWT-019. |
+| `check-home-untouched.mjs` | check-home-untouched — did this run write anywhere UDS writes under HOME? |
+| `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 / OWT-018 / OWT-019 — repo entry point. |
 | `check-orphan-specs.ps1` | Check Orphan Specs |
 | `check-orphan-specs.sh` | Orphan Spec Detection Script |
 | `check-prompt-footprint.mjs` | Prompt Footprint Ratchet — DEC-117 D2/L2 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.14.0-beta.1",
+  "version": "6.14.0-beta.3",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/commands/check.js

@@ -1281,6 +1281,15 @@ export function checkPreCommitWiring(projectPath, msg) {
   const result = checkPreCommitHookWiring(projectPath);
   if (!result.relevant) return; // 沒有 UDS 管理的 hook
 
+  // 與 wiring 無關的獨立缺陷面：hook 即使已接上，仍可能請 npm 去解析裸名稱 `uds`
+  // ——npm registry 上那個名稱不是本專案。見 git-hooks.js buildPreCommitBlock。
+  if (result.legacyBareUds) {
+    console.log(chalk.yellow((msg.hookBareUdsTitle || '⚠ [pre-commit] {file} asks npm to run the bare name "uds", which on the npm registry is an unrelated package.')
+      .replace('{file}', result.hookFile)));
+    console.log(chalk.gray(msg.hookBareUdsFix || '  Fix: run `uds update`.'));
+    console.log();
+  }
+
   if (result.wired) {
     // 🔴 「已確認會執行」在 POSIX 上為真，在 Windows 上不一定——git for
     // Windows 沒有 POSIX 的 ENOEXEC → /bin/sh 後備機制，缺 shebang 的 hook

package/src/commands/init.js

@@ -1,7 +1,6 @@
 import chalk from 'chalk';
 import { createSpinner } from '../utils/spinner.js';
-import { execSync } from 'child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
 import { join } from 'path';
 import {
   manifestExists as isInitialized,
@@ -28,7 +27,9 @@ 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';
+import { newRecorder, mkdirTracked, recordFile, persistRecorder, RECORD_KINDS } from '../core/install-records.js';
+import { wireGitHooksPath, getLocalHooksPathConfig, stripLegacyHuskyShLine, ensureShebang, hookRunsUdsCheck, buildPreCommitBlock } from '../utils/git-hooks.js';
+import { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
 
 /**
  * Init command - initialize standards in current project
@@ -52,6 +53,8 @@ export async function initCommand(options) {
   if (isInitialized(projectPath)) {
     console.log(chalk.yellow(msg.alreadyInitialized));
     console.log(chalk.gray(`  ${msg.useUpdateOrDelete}`));
+    // `init` cannot run twice, so `--with-hooks` has no effect here; say where the door is.
+    if (options.withHooks) console.log(chalk.yellow(`  ${msg.useUpdateWithHooks}`));
     return;
   }
 
@@ -211,7 +214,11 @@ export async function initCommand(options) {
             skillHashes: skillsResults.skillHashes,
             commandHashes: skillsResults.commandHashes,
             integrationBlockHashes: integrationResults.integrationBlockHashes,
-            manifestIntegrationConfigs: integrationResults.manifestIntegrationConfigs
+            manifestIntegrationConfigs: integrationResults.manifestIntegrationConfigs,
+            createdIntegrationFiles: [
+              ...(integrationResults.createdFiles ?? []),
+              ...(agentsMdResult.created ? [agentsMdResult.path] : [])
+            ]
           };
         },
         // A half-installed project must never be committed: if any installer
@@ -256,9 +263,13 @@ export async function initCommand(options) {
   }
 
   // 4.6. Install enforcement hooks (if --with-hooks)
+  // What this step writes is recorded in the manifest (installedArtifacts) so
+  // `uds uninstall` can remove exactly it — hook scripts, and the folders UDS had
+  // to create for them — and leave everything the adopter put there alone.
+  const installRecorder = newRecorder();
   if (config.withHooks) {
     const { installHooks } = await import('../installers/hooks-installer.js');
-    const hookResult = installHooks(projectPath);
+    const hookResult = installHooks(projectPath, { recorder: installRecorder });
     if (hookResult.installed) {
       console.log(chalk.green(
         `  ✓ Enforcement hooks installed (${hookResult.scriptsCount} scripts, `
@@ -290,7 +301,7 @@ export async function initCommand(options) {
     const selectedTools = config.integrations || config.aiTools || [];
     if (selectedTools.includes('codex')) {
       const { installCodexHooks } = await import('../installers/hooks-installer.js');
-      const codexResult = installCodexHooks(projectPath);
+      const codexResult = installCodexHooks(projectPath, { recorder: installRecorder });
       if (codexResult.installed) {
         console.log(chalk.green('  ✓ Codex Stop hook installed (turn-completion-integrity)'));
         // Measured 2026-09-28 (codex-cli 0.155.1): Codex skips a project hook
@@ -304,7 +315,7 @@ export async function initCommand(options) {
     }
     if (selectedTools.includes('gemini-cli')) {
       const { installGeminiHooks } = await import('../installers/hooks-installer.js');
-      const geminiResult = installGeminiHooks(projectPath);
+      const geminiResult = installGeminiHooks(projectPath, { recorder: installRecorder });
       if (geminiResult.installed) {
         console.log(chalk.green('  ✓ Gemini CLI AfterAgent hook installed (turn-completion-integrity; Gemini CLI is legacy — see the standard)'));
       } else {
@@ -313,7 +324,7 @@ export async function initCommand(options) {
     }
     if (selectedTools.includes('antigravity')) {
       const { installAgyHooks } = await import('../installers/hooks-installer.js');
-      const agyResult = installAgyHooks(projectPath);
+      const agyResult = installAgyHooks(projectPath, { recorder: installRecorder });
       if (agyResult.installed) {
         console.log(chalk.green('  ✓ Antigravity CLI Stop hook installed (turn-completion-integrity; .agents/hooks.json)'));
         // Verified 2026-09-29 (agy 1.2.12): single turn, no tool calls, `agy -p`.
@@ -326,6 +337,15 @@ export async function initCommand(options) {
     }
   }
 
+  // 4.7. Record the integration files UDS created from nothing, and the hook
+  // files/folders written above. Their text outside the UDS marker block (the
+  // `> Auto-generated by ...` header, the generated sections) is what makes
+  // "delete the whole file" provable at uninstall time.
+  for (const created of combinedResults.createdIntegrationFiles ?? []) {
+    recordFile(installRecorder, projectPath, created, RECORD_KINDS.INTEGRATION_FILE);
+  }
+  persistRecorder(projectPath, installRecorder);
+
   // 5. Setup Pre-commit Hook
   await setupHuskyHook(projectPath);
 
@@ -337,7 +357,7 @@ export async function initCommand(options) {
  * - Node.js projects: use husky
  * - Non-Node.js projects: write native .git/hooks/pre-commit
  */
-export async function setupHuskyHook(projectPath, { allowInTest = false } = {}) {
+export async function setupHuskyHook(projectPath, { allowInTest = false, platform = process.platform } = {}) {
   // 2026-07-30：本函式在跑測試時改寫了 universal-dev-standards 自己
   // ——`npm install --save-dev husky`、改 package.json、建 .husky/pre-commit。
   //
@@ -357,6 +377,9 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
 
   const isNodeProject = existsSync(join(projectPath, 'package.json'));
 
+  // What this function creates, for `uds uninstall` (see core/install-records.js).
+  const recorder = newRecorder();
+
   if (isNodeProject) {
     console.log(chalk.cyan('Configuring Pre-commit Hook...'));
 
@@ -434,7 +457,7 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
     // 3. Ensure .husky directory exists
     if (!existsSync(huskyDir)) {
       try {
-        mkdirSync(huskyDir, { recursive: true });
+        mkdirTracked(recorder, projectPath, huskyDir);
       } catch (e) {
         console.log(chalk.red(`  ✗ Failed to create .husky directory: ${e.message}`));
         return;
@@ -443,8 +466,10 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
 
     // 4. Add pre-commit hook content
     const preCommitPath = join(huskyDir, 'pre-commit');
-    const udsCmd = 'npx uds check';
 
+    // Only a hook file UDS creates from nothing can later be proven to be wholly
+    // its own; one that already existed is appended to and stays the adopter's.
+    const preCommitExisted = existsSync(preCommitPath);
     try {
       // husky v9's own templates carry no shebang, no `_/husky.sh` sourcing
       // (that is v8 syntax, deprecated in v9 and removed in v10). Verified
@@ -462,6 +487,18 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
       // — 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.
+      // A hook an older UDS wrote asks npx for the bare name `uds`, which on the
+      // npm registry is an unrelated package (see buildPreCommitBlock). Swap the
+      // line UDS itself wrote for the current block before anything else reads
+      // the file; a line the adopter edited is left alone and reported below.
+      const legacy = existsSync(preCommitPath) ? migrateLegacyHuskyHook(projectPath) : null;
+      if (legacy?.state === 'migrated') {
+        console.log(chalk.green('  ✓ Replaced the pre-commit 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'));
+      }
+      for (const k of legacy?.kept ?? []) {
+        console.log(chalk.yellow(`  ⚠ .husky/pre-commit line ${k.line} ("${k.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" (with the CLI installed in this project or on PATH).`));
+      }
+
       let content = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : '';
 
       // A pre-existing file may still carry husky v8's `_/husky.sh` sourcing
@@ -477,10 +514,10 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
       const { content: destripped, removed: hadLegacyLine } = stripLegacyHuskyShLine(content);
       content = destripped;
 
-      const needsAppend = !content.includes('uds check');
+      const needsAppend = !hookRunsUdsCheck(content);
       if (needsAppend) {
         const sep = content && !content.endsWith('\n') ? '\n' : '';
-        content = `${content}${sep}\n# UDS Standard Check\n${udsCmd}\n`;
+        content = `${content}${sep}\n${buildPreCommitBlock()}`;
       }
 
       const { content: shebanged, added: addedShebang } = ensureShebang(content);
@@ -488,10 +525,22 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
 
       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 (!preCommitExisted) recordFile(recorder, projectPath, '.husky/pre-commit', RECORD_KINDS.GIT_HOOK);
+        // 🔴 Was `execSync(`chmod +x ...`)` inside try/catch. On Windows that
+        // spawned cmd.exe, which printed "'chmod' is not recognized as an
+        // internal or external command" straight to the user's terminal —
+        // execSync inherits the child's stderr by default, so the catch hid the
+        // failure from the code and left it loud for the human (adopter report,
+        // 6.14.0-beta.2, Windows 11). No shell is needed to change a mode, and
+        // Windows has no exec bit to set (git for Windows runs the hook through
+        // its own sh regardless), so it is skipped there.
+        if (platform !== 'win32') {
+          try {
+            chmodSync(preCommitPath, 0o755);
+          } catch {
+            // A filesystem that refuses the mode change (FAT, some mounts) is not
+            // a reason to fail the install; git reports a non-executable hook itself.
+          }
         }
       }
 
@@ -510,6 +559,8 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
       console.log(chalk.red(`  ✗ Failed to configure pre-commit hook: ${e.message}`));
     }
 
+    persistRecorder(projectPath, recorder);
+
     // 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
@@ -565,7 +616,7 @@ export async function setupHuskyHook(projectPath, { allowInTest = false } = {})
 
       if (existsSync(hookPath)) {
         const existingContent = readFileSync(hookPath, 'utf-8');
-        if (existingContent.includes('uds check')) {
+        if (hookRunsUdsCheck(existingContent)) {
           console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
         } else {
           // Never clobber an adopter's own hook (this fix — it used to be
@@ -595,6 +646,10 @@ uds check 2>/dev/null || true
 echo "Pre-commit checks passed"
 `;
         writeFileSync(hookPath, hookContent, { mode: 0o755 });
+        // Created from nothing (the branch above is "file does not exist"), so the
+        // whole file is UDS's — record its hash for `uds uninstall`.
+        recordFile(recorder, projectPath, '.git/hooks/pre-commit', RECORD_KINDS.GIT_HOOK);
+        persistRecorder(projectPath, recorder);
         console.log(chalk.green('  ✓ Installed .git/hooks/pre-commit (native git hook)'));
       }
     } catch (e) {

package/src/commands/open-work.js

@@ -0,0 +1,60 @@
+/**
+ * `uds open-work` — the open-work-tracking reference checks (OWT-017 / 018 / 019)
+ * as a command, so an adopter can run them from the npm package.
+ *
+ * This file holds no rules. The one body of them is
+ * `../utils/open-work-tracking.mjs`; this only turns commander's parsed
+ * arguments back into the argv that module's `main()` reads, so the command and
+ * `node scripts/check-open-work-tracking.mjs` cannot disagree.
+ *
+ * Exit codes are the module's and are not translated: 0 no violation, 1
+ * violation, 2 cannot decide (no structure found, git failed, or the checker's
+ * own self-test arms failed). 2 is NOT a pass. `process.exitCode` is set rather
+ * than calling `process.exit()`, so commander's post-action hook still runs.
+ *
+ * It is a reference decision procedure offered as evidence (OWT-015), not a
+ * gate, and its coverage is unknown and uncalibrated (OWT-011, OWT-016); the
+ * module prints both statements on every run.
+ *
+ * @module commands/open-work
+ */
+
+import { main } from '../utils/open-work-tracking.mjs';
+
+/** Append `--name value` when the option was given. */
+function withOption(argv, name, value) {
+  if (value !== undefined && value !== null) argv.push(name, String(value));
+  return argv;
+}
+
+function run(argv) {
+  process.exitCode = main(argv);
+}
+
+/** uds open-work next-action [files...] [--root DIR] [--id-pattern RE] — OWT-019 */
+export function openWorkNextActionCommand(files = [], options = {}) {
+  const argv = ['next-action'];
+  withOption(argv, '--root', options.root);
+  withOption(argv, '--id-pattern', options.idPattern);
+  run([...argv, ...files]);
+}
+
+/** uds open-work revision (--file PATH --base REV | --before FILE --after FILE) — OWT-018 */
+export function openWorkRevisionCommand(options = {}) {
+  const argv = ['revision'];
+  withOption(argv, '--file', options.file);
+  withOption(argv, '--base', options.base);
+  withOption(argv, '--before', options.before);
+  withOption(argv, '--after', options.after);
+  run(argv);
+}
+
+/** uds open-work separation [files...] — OWT-017 */
+export function openWorkSeparationCommand(files = []) {
+  run(['separation', ...files]);
+}
+
+/** uds open-work self-test — run the checker's own arms and nothing else */
+export function openWorkSelfTestCommand() {
+  run(['--self-test']);
+}