universal-dev-standards 6.3.9 → 6.3.10

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.9
-translation_version: 6.3.9
-last_synced: 2026-08-09
+source_version: 6.3.10
+translation_version: 6.3.10
+last_synced: 2026-08-10
 status: current
 ---
 
@@ -17,6 +17,15 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.10] - 2026-08-10
+
+### 修复
+
+- **`--plan` 会被另外四个标志吃掉，而唯一能防止破坏的正是被忽略的那一个。** `uds update --plan --skills` 会安装 Skills；`--plan --sync-refs` 会改写集成文件与 manifest。那个文档写着「Show reconciliation plan without executing (like terraform plan)」的标志被静默丢弃——因为范围标志（`--skills`、`--commands`、`--integrations-only`、`--sync-refs`）在一条先到先得、每个分支都 return 的链里，排在模式标志（`--plan`、`--apply`、`--force`、`--rollback`）之前。`--integrations-only` 早在 2026-07-30 就为了同一件事修过；另外三个没有被碰，十一天后它们仍在写文件。现在模式先于范围决定，而测试改为**从 CLI 定义读出标志清单**而非人工列举——之后新增的标志不需要有人记得就会被覆盖。第四个实例正是那个测试找出来的。
+- **`--apply --skills` 只升级 Skills、安静地把标准留在原地，并报告成功。** 同一条链：`--skills` 在协调器执行之前就 return 了。以此方式升级一个真实项目，结果它停在旧的标准版本，而屏幕上没有任何一行说明。现在 `--apply` 与 `--force` 会执行协调**并且**执行所要求的范围。
+- **没有人能回答的确认提示，返回 exit 0。** 非交互 shell 下 `@inquirer/prompts` 会抛出 `ExitPromptError`，该异常从未被捕获而进程仍以 exit code 0 结束——于是在 CI 里「什么都没写」与「更新成功」返回同一个值。现在它会说明没有任何东西被写入、指向 `--yes`，并以 exit 2 结束。检测方式是**提示真的失败了**，而不是探测 `process.stdin.isTTY`——后者在两个方向上都会答错。
+- **`--rollback` 现在会说明 `--skills`／`--commands` 无法缩小它的范围**，而不是接受它们却照样还原全部。
+
 ## [6.3.9] - 2026-08-09
 
 ### 修复

package/bundled/locales/zh-CN/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.3.9 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.10 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 

package/bundled/locales/zh-TW/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.9
-translation_version: 6.3.9
-last_synced: 2026-08-09
+source_version: 6.3.10
+translation_version: 6.3.10
+last_synced: 2026-08-10
 status: current
 ---
 
@@ -17,6 +17,15 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.10] - 2026-08-10
+
+### 修正
+
+- **`--plan` 會被另外四個旗標吃掉，而唯一能防止破壞的正是被忽略的那一個。** `uds update --plan --skills` 會安裝 Skills；`--plan --sync-refs` 會改寫整合檔與 manifest。那個文件寫著「Show reconciliation plan without executing (like terraform plan)」的旗標被靜默丟棄——因為範圍旗標（`--skills`、`--commands`、`--integrations-only`、`--sync-refs`）在一條先到先得、每個分支都 return 的鏈裡，排在模式旗標（`--plan`、`--apply`、`--force`、`--rollback`）之前。`--integrations-only` 早在 2026-07-30 就為了同一件事修過；另外三個沒有被碰，十一天後它們仍在寫檔。現在模式先於範圍決定，而測試改為**從 CLI 定義讀出旗標清單**而非人工列舉——之後新增的旗標不需要有人記得就會被涵蓋。第四個實例正是那個測試找出來的。
+- **`--apply --skills` 只升級 Skills、安靜地把標準留在原地，並回報成功。** 同一條鏈：`--skills` 在調和器執行之前就 return 了。以此方式升級一個真實專案，結果它停在舊的標準版本，而畫面上沒有任何一行說明。現在 `--apply` 與 `--force` 會執行調和**並且**執行所要求的範圍。
+- **沒有人能回答的確認提示，回傳 exit 0。** 非互動 shell 下 `@inquirer/prompts` 會擲 `ExitPromptError`，該例外從未被攔截而程序仍以 exit code 0 結束——於是在 CI 裡「什麼都沒寫」與「更新成功」回傳同一個值。現在它會說明沒有任何東西被寫入、指向 `--yes`，並以 exit 2 結束。偵測方式是**提示真的失敗了**，而不是探測 `process.stdin.isTTY`——後者在兩個方向上都會答錯。
+- **`--rollback` 現在會說明 `--skills`／`--commands` 無法縮小它的範圍**，而不是接受它們卻照樣還原全部。
+
 ## [6.3.9] - 2026-08-09
 
 ### 修正

package/bundled/locales/zh-TW/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.3.9 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.10 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。
 

package/package.json

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

package/src/commands/update.js

@@ -334,9 +334,13 @@ export async function updateCommand(options) {
   console.log(chalk.bold(msg.title));
   console.log(chalk.gray('─'.repeat(50)));
 
-  // Handle --sync-refs option
+  // 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
+  // reconciler — but "above the dispatch" is exactly how --plan got dropped by
+  // three other branches, so it passes the flag down instead of assuming.
   if (options.syncRefs) {
-    await syncIntegrationReferences(projectPath, manifest);
+    await syncIntegrationReferences(projectPath, manifest, { plan: !!options.plan });
     return;
   }
 
@@ -350,39 +354,68 @@ export async function updateCommand(options) {
     return;
   }
 
-  // Handle --skills option
-  if (options.skills) {
-    await updateSkillsOnly(projectPath, manifest, options);
-    return;
-  }
-
-  // Handle --commands option
-  if (options.commands) {
-    await updateCommandsOnly(projectPath, manifest, options);
-    return;
-  }
-
-  // Handle --rollback option (DSR)
+  // ── Flags come in two axes, and they must not eat each other ──────────
+  // // implements XSPEC-372 R1/R2
+  //
+  //   mode  : --plan / --apply / --force / --rollback   (what to do)
+  //   scope : --skills / --commands / --integrations-only / --standards-only
+  //
+  // These used to sit in one first-match-wins if/return chain with the scope
+  // flags first. `--plan --skills` therefore *installed* Skills — the flag
+  // documented as "without executing" was dropped with nothing said — and
+  // `--apply --skills` upgraded Skills while silently leaving the standards
+  // behind, reporting success either way. Both measured 2026-08-10 while
+  // upgrading four repos to 6.3.9.
+  //
+  // Mode is now decided first, and scope narrows it instead of replacing it.
+  const scopedToSkills = !!options.skills;
+  const scopedToCommands = !!options.commands;
+
+  // Handle --rollback option (DSR). It restores a whole backup, so a scope
+  // flag cannot narrow it — say so rather than appearing to honour it.
   if (options.rollback) {
+    if (scopedToSkills || scopedToCommands) {
+      console.log(chalk.yellow('  ! --rollback restores a complete backup; --skills/--commands cannot narrow it and are ignored.'));
+      console.log();
+    }
     await handleRollback(projectPath);
     return;
   }
 
-  // Handle --plan option (DSR dry-run)
+  // Handle --plan option (DSR dry-run). Nothing below this line writes.
   if (options.plan) {
-    await handlePlan(projectPath, options);
+    if (!scopedToSkills && !scopedToCommands) {
+      await handlePlan(projectPath, options);
+    }
+    if (scopedToSkills) await planSkills(projectPath, manifest, options);
+    if (scopedToCommands) await planCommands(projectPath, manifest, options);
+    return;
+  }
+
+  // Handle --apply / --force (DSR reconciliation), composing with scope.
+  // A scope flag alone still means "only that scope"; combined with a mode it
+  // means "that mode, and also that scope" — the reconciler tracks Skills
+  // files only when the manifest records them, so `--skills` is not redundant.
+  if (options.apply || options.force) {
+    if (!scopedToSkills && !scopedToCommands) {
+      await handleReconcile(projectPath, options, { force: !!options.force });
+      return;
+    }
+    await handleReconcile(projectPath, options, { force: !!options.force });
+    // These exit the process on completion, so run Skills last.
+    if (scopedToCommands) await updateCommandsOnly(projectPath, manifest, options);
+    if (scopedToSkills) await updateSkillsOnly(projectPath, manifest, options);
     return;
   }
 
-  // Handle --apply option (DSR: execute the plan `--plan` prints)
-  if (options.apply) {
-    await handleReconcile(projectPath, options, { force: false });
+  // Scope without a mode: the original shortcuts.
+  if (scopedToSkills) {
+    await updateSkillsOnly(projectPath, manifest, options);
     return;
   }
 
-  // Handle --force option (DSR force reconciliation)
-  if (options.force) {
-    await handleReconcile(projectPath, options, { force: true });
+  if (scopedToCommands) {
+    await updateCommandsOnly(projectPath, manifest, options);
     return;
   }
 
@@ -494,11 +527,8 @@ export async function updateCommand(options) {
   console.log();
 
   // Confirm
-  if (!options.yes) {
-    const confirmed = await inquirerConfirm({
-      message: msg.confirmUpdate,
-      default: true
-    });
+  {
+    const confirmed = await confirmOrFail({ message: msg.confirmUpdate, options });
 
     if (!confirmed) {
       console.log(chalk.yellow(msg.updateCancelled));
@@ -558,10 +588,7 @@ export async function updateCommand(options) {
       shouldInstallNew = true;
     } else {
       // Interactive mode: ask user
-      const installNew = await inquirerConfirm({
-        message: msg.installNewStandards,
-        default: true
-      });
+      const installNew = await confirmOrFail({ message: msg.installNewStandards, options });
       shouldInstallNew = installNew;
     }
 
@@ -886,9 +913,9 @@ export async function updateCommand(options) {
     if (options.yes) {
       shouldRestore = true;
     } else {
-      const restoreMissing = await inquirerConfirm({
+      const restoreMissing = await confirmOrFail({
         message: (msg.restoreMissingPrompt || 'Restore {count} missing file(s)?').replace('{count}', missingFiles.length),
-        default: true
+        options
       });
       shouldRestore = restoreMissing;
     }
@@ -1440,6 +1467,40 @@ export function regenerateIntegrations(projectPath, manifest) {
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
  */
+/**
+ * Ask for confirmation, or fail loudly when there is nobody to ask.
+ * // implements XSPEC-372 R3
+ *
+ * `@inquirer/prompts` throws `ExitPromptError` when stdin is not a TTY. That
+ * exception was never caught, and the process still ended with **exit code 0**
+ * — so in CI a run that wrote nothing was indistinguishable from a successful
+ * update. Measured 2026-08-10 on `uds update --apply` and reproduced with
+ * `--force --apply`: zero files written, `echo $?` printed 0.
+ *
+ * Not auto-confirming: that would give an unattended environment broader
+ * permission than an interactive one. Exit 2 rather than 1 keeps "could not
+ * run" distinct from "ran and found a problem".
+ */
+async function confirmOrFail({ message, defaultValue = true, options }) {
+  if (options?.yes) return true;
+  try {
+    return await inquirerConfirm({ message, default: defaultValue });
+  } catch (err) {
+    // Detect by what the prompt does, not by probing `process.stdin.isTTY`.
+    // isTTY is a proxy for "somebody can answer", and it is wrong in both
+    // directions — a mocked or wrapped stdin answers fine with isTTY unset.
+    // The prompt failing IS the condition; anything else is a guess about it.
+    const closed = err?.name === 'ExitPromptError' || /force closed the prompt/i.test(err?.message || '');
+    if (!closed) throw err;
+    console.log();
+    console.log(chalk.red('Cannot ask for confirmation: there is nothing attached to answer the prompt (non-interactive shell, CI, or a pipe).'));
+    console.log(chalk.gray(`  Pending question: ${message}`));
+    console.log(chalk.gray('  Re-run with --yes to confirm up front. Nothing has been written.'));
+    console.log();
+    process.exit(2);
+  }
+}
+
 async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   const msg = t().commands.update;
 
@@ -1548,7 +1609,7 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
  */
-async function syncIntegrationReferences(projectPath, manifest) {
+async function syncIntegrationReferences(projectPath, manifest, { plan = false } = {}) {
   const msg = t().commands.update;
 
   console.log(chalk.cyan(msg.syncingRefs));
@@ -1615,6 +1676,12 @@ async function syncIntegrationReferences(projectPath, manifest) {
       outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || config.outputLanguage || config.commitLanguage || 'english'
     };
 
+    if (plan) {
+      console.log(chalk.yellow(`  ~ ${integrationPath}: categories would change to ${expectedCategories.join(', ') || '(none)'} (dry run — nothing is written)`));
+      updatedCount++;
+      continue;
+    }
+
     const result = writeIntegrationFile(toolName, newConfig, projectPath);
 
     if (result.success) {
@@ -1657,7 +1724,11 @@ async function syncIntegrationReferences(projectPath, manifest) {
   if (updatedCount > 0) {
     manifest.version = '3.3.0';
     refreshIntegrationBlockHashes(manifest, projectPath);
-    writeManifest(manifest, projectPath);
+    if (plan) {
+      console.log(chalk.gray('  (dry run — the manifest was not written)'));
+    } else {
+      writeManifest(manifest, projectPath);
+    }
   }
 
   // Summary
@@ -1680,6 +1751,83 @@ async function syncIntegrationReferences(projectPath, manifest) {
  * @param {Object} manifest - Manifest object
  * @param {Object} [options] - CLI options (forwarded for locale resolution)
  */
+/**
+ * `--plan --skills`: say what a Skills update would do, and write nothing.
+ * // implements XSPEC-372 R1
+ *
+ * Deliberately does not call installSkillsToMultipleAgents and roll back.
+ * "Write then restore" leaves a broken tree if it dies halfway, which is worse
+ * than having no dry run at all — the same reasoning as the integrations plan.
+ */
+async function planSkills(projectPath, manifest, options) {
+  const repoInfo = getRepositoryInfo();
+  const latestVersion = repoInfo.skills.version;
+  const installations = (manifest.skills?.installations || []).filter(i => i.level !== 'marketplace');
+
+  console.log(chalk.bold('=== Skills Plan (dry run — nothing is written) ==='));
+
+  if (installations.length === 0) {
+    // Not "up to date". The manifest records no installation, so a Skills
+    // update has nothing to act on — which is a different answer, and the one
+    // that explains why `--skills` appears to do nothing here.
+    console.log(chalk.yellow('  No Skills installations recorded in the manifest — nothing for --skills to update.'));
+    if (manifest.skills?.installed) {
+      console.log(chalk.gray('  (manifest.skills.installed is true but installations[] is empty; run `uds skills` to re-register)'));
+    }
+    console.log();
+    return;
+  }
+
+  let changed = 0;
+  for (const inst of installations) {
+    const info = getInstalledSkillsInfoForAgent(inst.agent, inst.level, projectPath);
+    const current = info?.version || 'unknown';
+    const dir = getSkillsDirForAgent(inst.agent, inst.level, projectPath);
+    if (current === latestVersion) {
+      console.log(chalk.gray(`  = ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} — unchanged`));
+    } else {
+      changed++;
+      console.log(chalk.yellow(`  ~ ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} → v${latestVersion}  ${dir}`));
+    }
+  }
+
+  console.log();
+  console.log(`Summary: ${changed} installation(s) would be updated, ${installations.length - changed} unchanged.`);
+  console.log(chalk.gray(`  Locale that would be used: ${resolveLocale(manifest, projectPath, options)}`));
+  console.log(chalk.gray('  Run `uds update --apply --yes --skills` to apply.'));
+  console.log();
+}
+
+/**
+ * `--plan --commands`: same contract as planSkills.
+ * // implements XSPEC-372 R1
+ */
+async function planCommands(projectPath, manifest, options) {
+  const installations = manifest.commands?.installations || [];
+
+  console.log(chalk.bold('=== Commands Plan (dry run — nothing is written) ==='));
+
+  if (installations.length === 0) {
+    console.log(chalk.yellow('  No slash-command installations recorded in the manifest — nothing for --commands to update.'));
+    console.log();
+    return;
+  }
+
+  for (const inst of installations) {
+    const agent = typeof inst === 'string' ? inst : inst.agent;
+    const level = typeof inst === 'string' ? 'project' : (inst.level || 'project');
+    const info = getInstalledCommandsForAgent(agent, level, projectPath);
+    const dir = getCommandsDirForAgent(agent, level, projectPath);
+    console.log(chalk.yellow(`  ~ ${getAgentDisplayName(agent)} (${level}): ${info?.count || 0} command(s) would be reinstalled  ${dir}`));
+  }
+
+  console.log();
+  console.log(`Summary: ${installations.length} installation(s) would be reinstalled.`);
+  console.log(chalk.gray(`  Locale that would be used: ${resolveLocale(manifest, projectPath, options)}`));
+  console.log(chalk.gray('  Run `uds update --apply --yes --commands` to apply.'));
+  console.log();
+}
+
 async function updateSkillsOnly(projectPath, manifest, options) {
   const msg = t().commands.update;
   const repoInfo = getRepositoryInfo();
@@ -2382,10 +2530,10 @@ async function handleReconcile(projectPath, options, { force }) {
   console.log();
 
   // Confirm unless --yes
-  if (!options.yes) {
-    const confirmed = await inquirerConfirm({
+  {
+    const confirmed = await confirmOrFail({
       message: `Apply ${planResult.plan.actions.length} changes?`,
-      default: true
+      options
     });
 
     if (!confirmed) {

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.3.9",
+  "version": "6.3.10",
   "lastUpdated": "2026-05-13",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "6.3.9"
+      "version": "6.3.10"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "6.3.9",
+      "version": "6.3.10",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -2236,7 +2236,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.3.9",
+      "version": "6.3.10",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2248,7 +2248,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.3.9",
+      "version": "6.3.10",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2260,7 +2260,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.3.9",
+      "version": "6.3.10",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2272,7 +2272,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.3.9",
+      "version": "6.3.10",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"