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

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

@@ -1,7 +1,7 @@
 # UDS 功能參考手冊
 
 > Universal Development Standards - 完整功能文件
-> Auto-generated | Last updated: 2026-09-23
+> Auto-generated | Last updated: 2026-09-29
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/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) (59)
+7. [腳本](#scripts) (63)
 
-**Total Features: 351**
+**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
@@ -478,7 +484,7 @@
 | `deployment-standards` | 1.1.0 | This standard defines guidelines for safely deploying software to production, co |
 | `deprecation-standards` | 1.1.0 |  |
 | `design-document-standards` | 1.0.0 |  |
-| `developer-memory` | 1.1.1 | This standard defines a structured system for capturing, retrieving, and surfaci |
+| `developer-memory` | 1.2.0 | This standard defines a structured system for capturing, retrieving, and surfaci |
 | `disaster-recovery-drill` | - |  |
 | `documentation-lifecycle` | 1.0.0 | This standard defines **when** to update documentation, **when** to check it, an |
 | `documentation-structure` | 1.5.0 | This standard defines a consistent documentation structure for software projects |
@@ -516,7 +522,7 @@
 | `mutation-testing` | 1.1.0 | Mutation testing evaluates test suite effectiveness by injecting artificial bugs |
 | `no-cicd-deployment` | - |  |
 | `observability-standards` | 1.0.0 |  |
-| `open-work-tracking` | 1.0.0 | The deferred-item-exit standard requires that a deferred item leave its document |
+| `open-work-tracking` | 1.1.0 | The deferred-item-exit standard requires that a deferred item leave its document |
 | `packaging-standards` | 1.1.0 | This standard defines a Recipe-based packaging framework that enables user proje |
 | `performance-standards` | 1.2.0 | This standard defines comprehensive guidelines for software performance engineer |
 | `pii-classification` | 1.1.0 | **Status**: Active | **Updated**: 2026-06-19 |  |
@@ -574,7 +580,7 @@
 | `timeout-standards` | - |  |
 | `token-budget` | - |  |
 | `translation-lifecycle-standards` | 1.0.1 | Translation lifecycle standards: MISSING vs OUTDATED distinction, semver-aware s |
-| `turn-completion-integrity` | 1.3.0 | An agent writes *"I'll do X next"* and then ends the turn without doing X. |
+| `turn-completion-integrity` | 1.5.0 | An agent writes *"I'll do X next"* and then ends the turn without doing X. |
 | `user-journey-testing` | - |  |
 | `user-story-mapping` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 |  |
 | `verification-evidence` | 1.3.0 | Establish an "Iron Law" that no task can be claimed as complete without verifica |
@@ -610,8 +616,11 @@
 | `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-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 |
 | `check-scope-sync.ps1` | Check Scope Sync |
 | `check-scope-sync.sh` | Scope Consistency Check Script |
 | `check-skill-next-steps-sync.ps1` | Check Skill Next Steps Sync |
@@ -625,6 +634,7 @@
 | `check-translation-hash-ratchet.sh` | XSPEC-392 R6 棘輪：新的翻譯必須帶 source_hash，既有的欠債冷凍為基線。 |
 | `check-translation-sync.ps1` | Check Translation Sync |
 | `check-translation-sync.sh` | Translation Sync Checker |
+| `check-upgrade-fidelity.sh` | Upgrade Fidelity Checker |
 | `check-usage-docs-sync.ps1` | Check if usage documentation needs to be regenerated |
 | `check-usage-docs-sync.sh` | check-usage-docs-sync.sh |
 | `check-version-sync.ps1` | Check Version Sync |

package/package.json

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

package/src/commands/init.js

@@ -52,6 +52,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;
   }
 
@@ -281,8 +283,8 @@ export async function initCommand(options) {
       }
     }
 
-    // turn-completion-integrity is also extended to Codex and Gemini CLI
-    // (2026-09-25), each with its own config file and output contract — see
+    // turn-completion-integrity is also extended to Codex, Gemini CLI and
+    // Antigravity CLI (2026-09-25; agy 2026-09-29), each with its own config file and output contract — see
     // installCodexHooks/installGeminiHooks in hooks-installer.js. Gated on the
     // tools the adopter actually selected: writing a hooks.json into every
     // project's .codex/ regardless of whether Codex is used would be noise,
@@ -311,6 +313,19 @@ export async function initCommand(options) {
         console.log(chalk.yellow(`  ⚠ Gemini CLI hook not installed — ${geminiResult.reason}`));
       }
     }
+    if (selectedTools.includes('antigravity')) {
+      const { installAgyHooks } = await import('../installers/hooks-installer.js');
+      const agyResult = installAgyHooks(projectPath);
+      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`.
+        // Multi-turn, tool-call turns and interactive mode are not verified —
+        // say so here, where the adopter believes it now works everywhere.
+        console.log(chalk.yellow('    ⚠ Verified against a real agy session for a single turn without tool calls in `agy -p` mode only; multi-turn, tool-call turns and interactive mode are not yet verified.'));
+      } else {
+        console.log(chalk.yellow(`  ⚠ Antigravity CLI hook not installed — ${agyResult.reason}`));
+      }
+    }
   }
 
   // 5. Setup Pre-commit Hook

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']);
+}

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, .claude/settings.json, .codex/hooks.json, .gemini/settings.json)`, value: 'hooks', checked: true },
+        { name: `${msg.categoryHooks} (.husky/pre-commit, .claude/settings.json, .codex/hooks.json, .gemini/settings.json, .agents/hooks.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/commands/update.js

@@ -46,6 +46,7 @@ import {
 } from '../config/ai-agent-paths.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import { detectAITools } from '../utils/detector.js';
+import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks } from '../installers/hooks-installer.js';
 import {
   promptSkillsInstallLocation,
   promptCommandsInstallation
@@ -451,6 +452,15 @@ export async function updateCommand(options) {
     return;
   }
 
+  // Handle --with-hooks (added 2026-09-29): install the enforcement hooks that are
+  // MISSING from an already-initialized project — the door `uds init --with-hooks`
+  // cannot be, because `uds init` refuses to run twice. Standalone like
+  // --claude-target and --sync-refs; and like them it honours --plan by writing nothing.
+  if (options.withHooks) {
+    await updateHooksOnly(projectPath, manifest, options);
+    return;
+  }
+
   // Handle --sync-refs option.
   // `--plan` is honoured here too. This branch is above the mode dispatch
   // because sync-refs is its own operation rather than a scope of the
@@ -1827,6 +1837,87 @@ async function switchClaudeTarget(projectPath, manifest, target, options) { // e
  * @param {Object} manifest - Manifest object (will be mutated with updated hashes)
  * @returns {{success: boolean, updated: string[], errors: string[]}}
  */
+/**
+ * `uds update --with-hooks [--ai-tool <list>] [--plan] [--force]`
+ *
+ * Adds the enforcement hooks that are missing; a hook that is already there is not
+ * touched, and the adopter's own hooks are never touched (see installMissingHooks).
+ * Exit code 1 only when there is no hook-capable tool to act on, or an install failed:
+ * "nothing to do" is 0, "could not tell which tool" is not.
+ *
+ * @param {string} projectPath
+ * @param {object} manifest
+ * @param {{ plan?: boolean, force?: boolean, aiTool?: string, yes?: boolean }} options
+ * @returns {Promise<void>}
+ */
+export async function updateHooksOnly(projectPath, manifest, options = {}) {
+  const ignored = ['skills', 'commands', 'syncRefs', 'integrationsOnly', 'standardsOnly', 'apply', 'rollback', 'prune']
+    .filter((k) => options[k]).map((k) => `--${k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())}`);
+  if (ignored.length) {
+    console.log(chalk.yellow(`  ! --with-hooks does one thing and does not compose; ${ignored.join(', ')} ignored.`));
+    console.log();
+  }
+
+  const capable = HOOK_CAPABLE_TOOLS.join(', ');
+  const resolved = resolveHookTools(projectPath, manifest, { aiTool: options.aiTool });
+
+  if (resolved.unknown.length) {
+    console.log(chalk.red(`  ✗ No hook installer for: ${resolved.unknown.join(', ')}`));
+    console.log(chalk.gray(`    Tools with hooks: ${capable}`));
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+  if (resolved.tools.length === 0) {
+    // Both non-interactive and interactive get the same message: there is no prompt to
+    // fall back to here, so the way to say which tool is spelled out instead.
+    console.log(chalk.yellow('  ⚠ Could not tell which AI tool to install hooks for.'));
+    console.log(chalk.gray('    Neither this project\'s manifest nor its files name one of: ' + capable + '.'));
+    console.log(chalk.gray('    Say which one:  uds update --with-hooks --ai-tool <tool>[,<tool>...]'));
+    console.log(chalk.gray('    e.g.            uds update --with-hooks --ai-tool antigravity'));
+    console.log(chalk.gray('    What is detected:  claude-code (.claude/ or CLAUDE.md) · codex (root AGENTS.md) · gemini-cli (GEMINI.md)'));
+    console.log(chalk.gray('                       antigravity (.agents/AGENTS.md, .agents/rules/, .agents/workflows/, .agents/plugins/ or .agents/hooks.json; .agents/skills/ is shared with Codex and does not count)'));
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(chalk.bold(options.plan ? 'Hooks — plan (nothing is written)' : 'Hooks'));
+  for (const tool of resolved.tools) {
+    console.log(chalk.gray(`  ${tool}: ${resolved.sources[tool].join(', ')}`));
+  }
+
+  const { results, scripts } = installMissingHooks(projectPath, resolved.tools, {
+    plan: !!options.plan,
+    overwriteScripts: !!options.force,
+  });
+
+  let failed = false;
+  for (const r of results) {
+    const rel = r.path ? relative(projectPath, r.path) || r.path : '';
+    if (r.outcome === 'installed') console.log(chalk.green(`  ✓ ${r.tool}: installed${r.repaired ? ' (replaced an out-of-date UDS entry)' : ''} — ${rel}`));
+    else if (r.outcome === 'would-install') console.log(chalk.cyan(`  + ${r.tool}: would install${r.repaired ? ' (replacing an out-of-date UDS entry)' : ''} — ${rel}`));
+    else if (r.outcome === 'unchanged') console.log(chalk.gray(`  · ${r.tool}: already installed, not touched — ${rel}`));
+    else { failed = true; console.log(chalk.yellow(`  ⚠ ${r.tool}: not installed — ${r.why}`)); }
+  }
+  const installedAny = results.some((r) => r.outcome === 'installed' || r.outcome === 'would-install');
+  if (installedAny && scripts.kept.length) {
+    console.log(chalk.yellow(`  ! ${scripts.kept.length} hook script(s) in scripts/hooks/ differ from this UDS version and were kept: ${scripts.kept.slice(0, 5).join(', ')}${scripts.kept.length > 5 ? ', ...' : ''}`));
+    console.log(chalk.gray('    Add --force to overwrite them with the shipped versions.'));
+  }
+  if (results.some((r) => r.tool === 'antigravity' && r.outcome === 'installed')) {
+    console.log(chalk.yellow('    ⚠ Verified against a real agy session for a single turn without tool calls in `agy -p` mode only; multi-turn, tool-call turns and interactive mode are not yet verified.'));
+  }
+  if (results.some((r) => r.tool === 'codex' && r.outcome === 'installed')) {
+    console.log(chalk.yellow('    ⚠ Codex will not run it until you trust it: open Codex in this project, trust the project, then run /hooks and trust this hook.'));
+  }
+  if (!results.some((r) => r.outcome === 'installed' || r.outcome === 'would-install')) {
+    console.log(chalk.gray('  Nothing to add.'));
+  }
+  console.log();
+  if (failed) process.exitCode = 1;
+}
+
 export function regenerateIntegrations(projectPath, manifest) {
   const aiTools = manifest.aiTools || [];
 

package/src/i18n/messages.js

@@ -930,6 +930,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',
@@ -2188,6 +2189,7 @@ export const messages = {
         title: '通用開發標準 - 初始化',
         alreadyInitialized: '⚠ 此專案已初始化標準。',
         useUpdateOrDelete: '使用 `uds update` 更新，或刪除 .standards/ 重新初始化。',
+        useUpdateWithHooks: '要為這個專案補裝執行關卡（含 UDS 在你初始化之後才支援的工具），請執行 `uds update --with-hooks`。',
         // Detection
         detectingProject: '正在偵測專案特性...',
         analysisComplete: '專案分析完成',
@@ -3158,6 +3160,7 @@ export const messages = {
         title: '通用开发标准 - 初始化',
         alreadyInitialized: '⚠ 此项目已初始化标准。',
         useUpdateOrDelete: '使用 `uds update` 更新，或删除 .standards/ 重新初始化。',
+        useUpdateWithHooks: '要为这个项目补装执行关卡（含 UDS 在你初始化之后才支持的工具），请执行 `uds update --with-hooks`。',
         // Detection
         detectingProject: '正在检测项目特性...',
         analysisComplete: '项目分析完成',