universal-dev-standards 6.1.0 → 6.2.0

package/bundled/skills/commands/skill-builder.md

@@ -33,10 +33,79 @@ It is backed by the `skill-builder` skill (`skills/skill-builder/SKILL.md`).
 | Complex | any of the above is exceeded | Create an XSPEC first (`/sdd`), then build |
 | Delta | modifying an existing Skill | Append `## MODIFIED` / `## ADDED`, bump version |
 
-## Implementation Note for AI
+## AI Agent Behavior | AI 代理行為
 
-When the user invokes `/skill-builder`:
-1. Read `skills/skill-builder/SKILL.md` for the full decision tree, placement
-   rules, workflow steps, and output checklist.
-2. Walk the user through path selection (Simple / Complex / Delta) and produce
-   the `SKILL.md` (plus `SKILL-CANDIDATES.md` update) per that skill.
+> Follows [AI Command Behavior Standards](../../core/ai-command-behavior.md)
+
+### Entry Router | 進入路由
+
+| Input | AI Action |
+|-------|-----------|
+| `/skill-builder` | 讀取 `SKILL-CANDIDATES.md`：有已達 3 次的候選 → 列出供選擇；無 → 詢問重複流程的描述 |
+| `/skill-builder <process description>` | 以該描述進入 Step 1，直接開始擷取流程 |
+
+### Interaction Script | 互動腳本
+
+先讀取 `skills/skill-builder/SKILL.md`，取得完整決策樹、放置規則、工作流程與輸出檢查表。
+
+#### Step 1–2: 擷取流程並登記候選
+
+1. 擷取重複序列：步驟與順序、目前手動執行過幾次、觸及哪些工具或檔案
+2. 開啟專案的 `SKILL-CANDIDATES.md`（首次則從 `templates/SKILL-CANDIDATES.md` 複製）
+
+**Decision: 觸發次數**
+- IF 尚未登記 → 新增列，填入目前次數
+- IF 已登記 → 次數 +1
+- IF 次數 < 3 → **告知尚未達觸發門檻，登記後停止，不建立 SKILL.md**
+- IF 次數 ≥ 3 → 標記觸發 ✅，繼續 Step 3
+
+🛑 **STOP**: 次數未達 3 時停止於此，等待使用者明確要求才破例
+
+#### Step 3: 路徑選擇
+
+回答 4 個判斷問題，判定路徑：
+
+- IF ≤7 步、無分支、<3 個標準、無原始碼產出 → **Simple**（Step 4a）
+- IF 上述任一超出 → **Complex**（Step 4b）
+- IF 修改既有 Skill → **Delta**（Step 4c）
+
+🛑 **STOP**: 展示判定結果與理由後等待使用者確認路徑
+
+#### Step 4: 依路徑分流
+
+- **4a Simple** — 以 `templates/SKILL-BRIEF-TEMPLATE.md` 填寫 Brief：觸發情境、3–7 個核心步驟、2–3 條 AC、明確的 out of scope
+- **4b Complex** — 執行 `/sdd` 建立 XSPEC；**XSPEC 未 Approved 前不進入 Step 5**
+- **4c Delta** — 標定既有 SKILL.md 受影響章節，於檔末加 `## MODIFIED Requirements` 或 `## ADDED Requirements`
+
+#### Step 5–7: 產出與登記
+
+1. **放置決策**：步驟引用專案特有路徑（如 `TECH-RADAR.md`、`DEC-*.md`）→ `{project}/.claude/skills/`；步驟為通用 → UDS `skills/{name}/` **並建立 zh-TW locale**
+2. 由 Brief 或 XSPEC 生成 SKILL.md，核對 frontmatter：`name`、`scope`、`description`、`allowed-tools`
+3. 回填 `SKILL-CANDIDATES.md`：觸發 ✅、Skill 欄填入
+4. 依 skill 的 commit 格式提交
+
+🛑 **STOP**: commit 前展示輸出檢查表結果，等待使用者確認
+
+### Stop Points | 停止點
+
+| Stop Point | 等待內容 |
+|-----------|---------|
+| 觸發次數 < 3 | 使用者是否明確要求破例建立 |
+| 路徑判定後 | 使用者確認 Simple / Complex / Delta |
+| Complex 路徑 | XSPEC 經 `/sdd` 建立並 Approved |
+| commit 前 | 使用者確認輸出檢查表 |
+
+### Error Handling | 錯誤處理
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| 未提供流程描述且無候選 | 詢問重複流程內容，**不得臆造流程** |
+| `SKILL-CANDIDATES.md` 不存在 | 從 `templates/SKILL-CANDIDATES.md` 複製後繼續 |
+| 觸發次數不足 3 次 | 登記候選後停止，說明門檻理由 |
+| 同名 Skill 已存在 | 改走 Delta 路徑，不覆蓋既有 SKILL.md |
+| 放置位置無法判定 | 列出「專案特有 vs 通用」判準請使用者裁定 |
+
+## References | 參考
+
+- [Skill Builder Skill](../skill-builder/SKILL.md)
+- Related: [/sdd](./sdd.md) (Complex path creates an XSPEC first)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -62,7 +62,7 @@
     "@inquirer/prompts": "^8.4.2",
     "chalk": "^5.3.0",
     "commander": "^15.0.0",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^5.2.1",
     "ora": "^9.4.0"
   },
   "devDependencies": {
@@ -70,7 +70,7 @@
     "@vitest/coverage-v8": "^4.1.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "eslint": "10.6.0",
+    "eslint": "10.7.0",
     "glob": "^13.0.1",
     "globals": "17.7.0",
     "husky": "^9.1.7",

package/src/commands/check.js

@@ -30,7 +30,7 @@ import {
   parseReferences,
   compareStandardsWithReferences
 } from '../utils/reference-sync.js';
-import { extractMarkedContent, getToolFilePath } from '../utils/integration-generator.js';
+import { extractMarkedContent, getToolFilePath, parseStandardsIndexCount } from '../utils/integration-generator.js';
 import { getToolFormat } from '../core/constants.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
 import { writeUpdateCache } from '../utils/update-checker.js';
@@ -39,17 +39,15 @@ import { WorkflowGate } from '../utils/workflow-gate.js';
 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';
 
 /**
  * Display the summary of file integrity status
  */
 function displayFileIntegritySummary(fileStatus, msg) {
-  if (fileStatus.unchanged.length > 0) {
-    for (const file of fileStatus.unchanged) {
-      console.log(chalk.green(`  ✓ ${file} (${msg.unchanged})`));
-    }
-  }
-
+  // XSPEC-342 R4（安靜通過）：不再逐檔列印「✓ 未變更」——實測佔 `uds check` 輸出約 70%
+  // （121 行中 85 行），把真正該讀的訊息（如標準落後）淹沒，也讓輸出大到被 agent 截斷。
+  // 未變更數仍保留在下方 summary 一行；此處只列印「需要注意」的檔（modified/missing/noHash）。
   if (fileStatus.modified.length > 0) {
     for (const file of fileStatus.modified) {
       console.log(chalk.yellow(`  ⚠ ${file} (${msg.modified})`));
@@ -164,7 +162,9 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
     }
 
     // Check integrations
-    for (const int of manifest.integrations) {
+    for (const intEntry of manifest.integrations) {
+      // 兩種形狀都要能解出路徑（XSPEC-343 R1）
+      const int = resolveIntegrationFile(intEntry) || intEntry;
       const filePath = join(projectPath, int);
       if (existsSync(filePath)) {
         fileStatus.noHash.push(int);
@@ -221,7 +221,7 @@ function initializeCheckContext(projectPath) {
 /**
  * Display standards adoption status and update information
  */
-function displayAdoptionStatus(manifest, msg, common, repoInfo) {
+function displayAdoptionStatus(manifest, msg, common, repoInfo, standardsUpdate) {
   console.log(chalk.green(msg.standardsInitialized));
   console.log();
   console.log(chalk.cyan(msg.adoptionStatus));
@@ -229,9 +229,15 @@ function displayAdoptionStatus(manifest, msg, common, repoInfo) {
   console.log(chalk.gray(`  ${common.version}: ${manifest.upstream.version}`));
   console.log();
 
-  // Check for updates (bundled registry)
-  if (manifest.upstream.version !== repoInfo.standards.version) {
-    console.log(chalk.yellow(msg.updateAvailable.replace('{current}', manifest.upstream.version).replace('{latest}', repoInfo.standards.version)));
+  // XSPEC-342 R1：判斷「已裝標準」是否落後 **npm 最新版**，而非 CLI 自己 bundled 的副本。
+  //   舊 bug：拿 manifest.upstream.version 比 repoInfo.standards.version（＝跑這支 CLI 帶的
+  //   標準副本）。CLI 一舊，bundled < npm 最新，就會吐出「6.1.0 → 5.12.1」這種倒退訊息，
+  //   且永遠說不出「你的標準過期了」。standardsUpdate = checkForUpdates(已裝標準版本)：
+  //   available ＝ 已裝 < npm 最新。離線時為 null → 靜默略過（不誤用 bundled 版本比對）。
+  if (standardsUpdate && !standardsUpdate.offline && standardsUpdate.available) {
+    console.log(chalk.yellow(msg.updateAvailable
+      .replace('{current}', manifest.upstream.version)
+      .replace('{latest}', standardsUpdate.latestVersion)));
     console.log(chalk.gray(`  ${msg.runUpdate}`));
     console.log();
   }
@@ -308,10 +314,17 @@ export async function checkCommand(options = {}) {
   console.log(chalk.bold(msg.title));
   console.log(chalk.gray('─'.repeat(50)));
 
-  // Display adoption info
-  displayAdoptionStatus(manifest, msg, common, repoInfo);
+  // XSPEC-342 R1：先問 npm 最新，判斷「已裝標準」是否落後（離線則跳過，不誤用 CLI bundled 版本）。
+  // fetchLatestVersion 有 60s 模組級快取，故此處與下方 checkCliVersion 共兩次呼叫只打一次網路。
+  let standardsUpdate = null;
+  if (!options.offline) {
+    standardsUpdate = await checkForUpdates(manifest.upstream.version, {
+      checkBeta: manifest.upstream.version.includes('-')
+    });
+  }
 
-  // Check for CLI updates from npm registry (unless --offline)
+  // Display adoption info
+  displayAdoptionStatus(manifest, msg, common, repoInfo, standardsUpdate);
 
   // Check for CLI updates from npm registry (unless --offline)
   if (!options.offline) {
@@ -717,7 +730,9 @@ function removeFromManifest(manifest, relativePath) {
   const fileName = basename(relativePath);
   manifest.standards = manifest.standards.filter(s => !s.endsWith(fileName));
   manifest.extensions = manifest.extensions.filter(e => typeof e !== 'string' || !e.endsWith(fileName));
-  manifest.integrations = manifest.integrations.filter(i => i !== relativePath);
+  manifest.integrations = manifest.integrations.filter(
+    i => (resolveIntegrationFile(i) || i) !== relativePath
+  );
 
   // Remove from integrationBlockHashes
   if (manifest.integrationBlockHashes && manifest.integrationBlockHashes[relativePath]) {
@@ -751,7 +766,7 @@ export function getSourcePathFromRelative(manifest, relativePath) {
   }
 
   // Check integrations - these might need special handling
-  if (manifest.integrations.includes(relativePath)) {
+  if (manifest.integrations.some(i => (resolveIntegrationFile(i) || i) === relativePath)) {
     // Integration files have different source paths
     const integrationMappings = {
       '.cursorrules': 'integrations/cursor/.cursorrules',
@@ -821,7 +836,8 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
   }
 
   // Process integrations
-  for (const int of manifest.integrations) {
+  for (const intEntry of manifest.integrations) {
+    const int = resolveIntegrationFile(intEntry) || intEntry;
     const fullPath = join(projectPath, int);
 
     const hashInfo = computeFileHash(fullPath);
@@ -1138,6 +1154,27 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
     // Report status - use all installed standards as the total
     const totalTrackable = standardsFiles.length;
 
+    // Index-mode blocks deliberately do NOT enumerate standards (XSPEC-358 R1);
+    // grepping for each name reports a false failure and points at `uds update`,
+    // which regenerates the identical block. Assert the declared count instead.
+    const declaredCount = parseStandardsIndexCount(content);
+    if (declaredCount !== null) {
+      if (declaredCount === totalTrackable) {
+        console.log(chalk.green(`  ✓ ${toolFile}:`));
+        console.log(chalk.gray(`    ${msg.standardsIndexPresent}`));
+        console.log(chalk.gray(`    ${msg.standardsIndexCount
+          ? msg.standardsIndexCount.replace('{count}', declaredCount)
+          : `Index declares ${declaredCount} standards (matches manifest)`}`));
+      } else {
+        console.log(chalk.yellow(`  ⚠ ${toolFile}:`));
+        console.log(chalk.yellow(`    ${msg.standardsIndexCountMismatch
+          ? msg.standardsIndexCountMismatch.replace('{declared}', declaredCount).replace('{actual}', totalTrackable)
+          : `Index declares ${declaredCount} standards but the manifest has ${totalTrackable}`}`));
+        hasIssues = true;
+      }
+      continue;
+    }
+
     if (hasStandardsIndex && missingStandards.length === 0) {
       console.log(chalk.green(`  ✓ ${toolFile}:`));
       console.log(chalk.gray(`    ${msg.standardsIndexPresent}`));
@@ -1209,6 +1246,25 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
   const content = readFileSync(agentsMdPath, 'utf-8');
   const installedStandards = (manifest.standards || []).map(s => basename(s));
 
+  // Same as the AI-tool integration check above: an index-mode block declares a
+  // count instead of listing names, so the name grep below cannot apply to it.
+  const declaredCount = parseStandardsIndexCount(content);
+  if (declaredCount !== null) {
+    const actual = installedStandards.length;
+    if (declaredCount === actual) {
+      console.log(chalk.green(`  ✓ AGENTS.md ${msg.standardsSynced || 'standards synced'} (${declaredCount})`));
+    } else {
+      console.log(chalk.yellow(`  ⚠ AGENTS.md ${msg.standardsOutOfSync || 'standards out of sync'} (${declaredCount} != ${actual})`));
+      console.log(chalk.gray(`    ${msg.runUpdateToSync || 'Run "uds update" to sync'}`));
+    }
+    const idxLineCount = content.split('\n').length;
+    if (idxLineCount > 150) {
+      console.log(chalk.yellow(`  ⚠ AGENTS.md ${msg.exceedsLineLimit || 'exceeds 150 line limit'} (${idxLineCount} lines)`));
+    }
+    console.log();
+    return;
+  }
+
   // Check standards listed in AGENTS.md vs manifest
   const aiYamlStandards = installedStandards.filter(s => s.endsWith('.ai.yaml'));
   let listedCount = 0;
@@ -1254,7 +1310,8 @@ function checkReferenceSync(manifest, projectPath, msg) {
 
   // Pre-scan: collect results for files that have references
   const results = [];
-  for (const integrationPath of manifest.integrations) {
+  for (const integrationEntry of manifest.integrations) {
+    const integrationPath = resolveIntegrationFile(integrationEntry) || integrationEntry;
     const fullPath = join(projectPath, integrationPath);
 
     if (!existsSync(fullPath)) continue;
@@ -1690,7 +1747,7 @@ function getFileStatusCounts(manifest, projectPath) {
     const allFiles = [
       ...manifest.standards.map(s => `.standards/${basename(s)}`),
       ...manifest.extensions.filter(e => typeof e === 'string').map(e => `.standards/${basename(e)}`),
-      ...manifest.integrations
+      ...manifest.integrations.map(i => resolveIntegrationFile(i) || i)
     ];
     for (const relativePath of allFiles) {
       const fullPath = join(projectPath, relativePath);

package/src/commands/config.js

@@ -49,6 +49,7 @@ import {
 } from '../utils/integration-generator.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import { regenerateIntegrations } from './update.js';
+import { mergeInstalledNames } from '../core/manifest.js';
 
 /**
  * Get localized message with fallback (for config-specific keys)
@@ -995,6 +996,7 @@ export async function runProjectConfiguration(options) {
                 manifest.skills.installations.push(inst);
               }
             }
+            manifest.skills.names = mergeInstalledNames(manifest.skills.names, skillResult);
             if (skillResult.allFileHashes) {
               manifest.skillHashes = { ...(manifest.skillHashes || {}), ...skillResult.allFileHashes };
             }
@@ -1031,6 +1033,7 @@ export async function runProjectConfiguration(options) {
                 manifest.commands.installations.push(inst);
               }
             }
+            manifest.commands.names = mergeInstalledNames(manifest.commands.names, cmdResult);
             if (cmdResult.allFileHashes) {
               manifest.commandHashes = { ...(manifest.commandHashes || {}), ...cmdResult.allFileHashes };
             }
@@ -1234,6 +1237,7 @@ async function handleSkillsConfiguration(manifest, projectPath, msgObj, common,
     } else {
       manifest.skills.installations.push(installations[0]);
     }
+    manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
     writeManifest(manifest, projectPath);
     return;
   }
@@ -1368,6 +1372,7 @@ async function handleSkillsConfiguration(manifest, projectPath, msgObj, common,
     // Update manifest - clear declined status for installed tools
     manifest.skills = manifest.skills || {};
     manifest.skills.installations = installations;
+    manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
     if (manifest.declinedFeatures?.skills) {
       manifest.declinedFeatures.skills = manifest.declinedFeatures.skills.filter(
         tool => !declinedToolsWithSupport.includes(tool)
@@ -1402,6 +1407,7 @@ async function handleSkillsConfiguration(manifest, projectPath, msgObj, common,
   // Update manifest
   manifest.skills = manifest.skills || {};
   manifest.skills.installations = installations;
+  manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
   writeManifest(manifest, projectPath);
 }
 
@@ -1465,6 +1471,7 @@ async function handleCommandsConfiguration(manifest, projectPath, msgObj, common
     } else {
       manifest.commands.installations.push(installations[0]);
     }
+    manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
     writeManifest(manifest, projectPath);
     return;
   }
@@ -1566,6 +1573,7 @@ async function handleCommandsConfiguration(manifest, projectPath, msgObj, common
     // Update manifest - clear declined status for installed tools
     manifest.commands = manifest.commands || {};
     manifest.commands.installations = declinedCommandsWithSupport;
+    manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
     if (manifest.declinedFeatures?.commands) {
       manifest.declinedFeatures.commands = manifest.declinedFeatures.commands.filter(
         tool => !declinedCommandsWithSupport.includes(tool)
@@ -1601,5 +1609,6 @@ async function handleCommandsConfiguration(manifest, projectPath, msgObj, common
   // Update manifest
   manifest.commands = manifest.commands || {};
   manifest.commands.installations = selectedAgents;
+  manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
   writeManifest(manifest, projectPath);
 }

package/src/commands/init.js

@@ -240,7 +240,21 @@ 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) {
+export async function setupHuskyHook(projectPath, { allowInTest = false } = {}) {
+  // 2026-07-30：本函式在跑測試時改寫了 universal-dev-standards 自己
+  // ——`npm install --save-dev husky`、改 package.json、建 .husky/pre-commit。
+  //
+  // 路徑是：測試呼叫 `initCommand({...})`（三個 init 測試檔都沒帶路徑、
+  // 也沒 mock child_process）→ `init.js` 取 `process.cwd()` → 走到這裡。
+  // 而下面那個 `.git` 是唯一的守衛，它只問「cwd 是不是一個 repo」：
+  //   從 `cli/` 跑 → cwd 沒有 .git → 提早 return，無害；
+  //   從 repo root 跑 → cwd **有** .git → 照跑，動到開發者自己的 repo。
+  // 同一批測試、不同 cwd，一個無害一個會寫檔。
+  //
+  // 守衛用顯式 opt-in 而非「偵測到測試就一律跳過」：`init.husky.test.js` 有十幾條
+  // 測試是**刻意**在暫存目錄裡驗這個函式的行為，一律跳過會把它們變成永遠通過的空測試。
+  if (process.env.VITEST && !allowInTest) return;
+
   const hasGit = existsSync(join(projectPath, '.git'));
   if (!hasGit) return;
 

package/src/commands/release.js

@@ -10,7 +10,7 @@
  */
 
 import chalk from 'chalk';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';

package/src/commands/update.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
 import { execSync } from 'child_process';
-import { existsSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
 import { readManifest, writeManifest, copyStandard, isInitialized } from '../utils/copier.js';
 import { getRepositoryInfo, getAllStandards, getStandardSource } from '../utils/registry.js';
@@ -11,7 +11,10 @@ import {
   writeIntegrationFile,
   getToolFilePath,
   writeAgentsMdSummary,
-  resolveContentModeForTool
+  resolveContentModeForTool,
+  generateIntegrationContent,
+  extractMarkedContent,
+  buildToolIntegrationConfig
 } from '../utils/integration-generator.js';
 import {
   calculateCategoriesFromStandards,
@@ -51,6 +54,8 @@ import {
 } from '../reconciler/index.js';
 import { restoreSingleFile } from './check.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
+import { resolveIntegrationFile } from '../core/constants.js';
+import { mergeInstalledNames } from '../core/manifest.js';
 
 /**
  * Determine the correct target directory for a standard file.
@@ -335,8 +340,12 @@ export async function updateCommand(options) {
   }
 
   // Handle --integrations-only option
+  // ⚠️ 這個分支在 --plan 檢查（見下）**之前**，所以必須自己處理 --plan——
+  //    否則 `--plan --integrations-only` 會靜默寫檔。2026-07-30 實測踩到：
+  //    以該組合驗證 XSPEC-358 的區塊變更時，它改了 machine-setup 的
+  //    CLAUDE.md 與 .standards/manifest.json，而旗標文件寫的是 "without executing"。
   if (options.integrationsOnly) {
-    await updateIntegrationsOnly(projectPath, manifest);
+    await updateIntegrationsOnly(projectPath, manifest, options);
     return;
   }
 
@@ -847,8 +856,9 @@ export async function updateCommand(options) {
     const fileName = basename(ext);
     allTrackedFiles.push(join('.standards', fileName));
   }
-  for (const int of (manifest.integrations || [])) {
-    const filePath = getToolFilePath(int);
+  for (const intEntry of (manifest.integrations || [])) {
+    // 兩種形狀都要能解出路徑（XSPEC-343 R1）
+    const filePath = resolveIntegrationFile(intEntry) || getToolFilePath(intEntry);
     if (filePath) {
       allTrackedFiles.push(filePath);
     }
@@ -951,6 +961,7 @@ export async function updateCommand(options) {
             ...(manifest.skills.installations || []),
             ...installSkills
           ];
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, skillResult);
 
           // Derive location from installations if not set
           if (!manifest.skills.location) {
@@ -987,6 +998,7 @@ export async function updateCommand(options) {
           // Update manifest version
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.version = repoInfo.skills.version;
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, updateResult);
 
           // Derive location from installations if not set
           if (!manifest.skills.location && manifest.skills.installations?.length > 0) {
@@ -1028,6 +1040,7 @@ export async function updateCommand(options) {
             ...(manifest.commands.installations || []),
             ...installCommands
           ];
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, cmdResult);
 
           // Update command hashes for integrity tracking
           if (cmdResult.allFileHashes) {
@@ -1053,6 +1066,7 @@ export async function updateCommand(options) {
           // Update manifest version
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.version = repoInfo.skills.version;
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, updateCmdResult);
 
           // Update command hashes for integrity tracking
           if (updateCmdResult.allFileHashes) {
@@ -1127,6 +1141,7 @@ export async function updateCommand(options) {
           manifest.skills.installed = true;
           manifest.skills.version = repoInfo.skills.version;
           manifest.skills.installations = [...(manifest.skills.installations || []), ...missingSkills];
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
           if (result.allFileHashes) {
             if (!manifest.skillHashes) manifest.skillHashes = {};
             Object.assign(manifest.skillHashes, result.allFileHashes);
@@ -1144,6 +1159,7 @@ export async function updateCommand(options) {
           const result = await installSkillsToMultipleAgents(outdatedSkills, null, projectPath, skillsLocale);
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.version = repoInfo.skills.version;
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
           if (!manifest.skills.location && manifest.skills.installations?.length > 0) {
             const levels = manifest.skills.installations.map(s => s.level).filter(Boolean);
             const uniqueLevels = [...new Set(levels)];
@@ -1168,6 +1184,7 @@ export async function updateCommand(options) {
           manifest.commands.installed = true;
           manifest.commands.version = repoInfo.skills.version;
           manifest.commands.installations = [...(manifest.commands.installations || []), ...missingCommands];
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
           if (result.allFileHashes) {
             if (!manifest.commandHashes) manifest.commandHashes = {};
             replaceCommandHashesForUpdatedAgents(manifest.commandHashes, result.allFileHashes);
@@ -1185,6 +1202,7 @@ export async function updateCommand(options) {
           const result = await installCommandsToMultipleAgents(outdatedCommands, null, projectPath, skillsLocale);
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.version = repoInfo.skills.version;
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
           if (result.allFileHashes) {
             if (!manifest.commandHashes) manifest.commandHashes = {};
             replaceCommandHashesForUpdatedAgents(manifest.commandHashes, result.allFileHashes);
@@ -1319,17 +1337,6 @@ export function regenerateIntegrations(projectPath, manifest) {
     return { success: true, updated: [], errors: [] };
   }
 
-  // Build installed standards list
-  const installedStandardsList = manifest.standards?.map(s => basename(s)) || [];
-
-  // Determine language setting
-  let commonLanguage = 'en';
-  if ((manifest.options?.output_language || manifest.options?.commit_language) === 'bilingual') {
-    commonLanguage = 'bilingual';
-  } else if ((manifest.options?.output_language || manifest.options?.commit_language) === 'traditional-chinese') {
-    commonLanguage = 'zh-tw';
-  }
-
   const results = {
     updated: [],
     errors: []
@@ -1345,19 +1352,8 @@ export function regenerateIntegrations(projectPath, manifest) {
       continue; // Skip if already generated (AGENTS.md sharing)
     }
 
-    // Resolve contentMode per tool based on tier
-    const savedMode = manifest.contentMode || 'auto';
-    const resolvedMode = resolveContentModeForTool(tool, savedMode);
-    const toolConfig = {
-      tool,
-      categories: ['anti-hallucination', 'commit-standards', 'code-review'],
-      language: commonLanguage,
-      installedStandards: installedStandardsList,
-      contentMode: resolvedMode.contentMode,
-      level: resolvedMode.level,
-      // Pass output_language for dynamic commit standards generation
-      outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english'
-    };
+    // Shared with the reconciler so both paths emit the identical block.
+    const toolConfig = buildToolIntegrationConfig(manifest, tool);
 
     const result = writeIntegrationFile(tool, toolConfig, projectPath);
     if (result.success) {
@@ -1392,7 +1388,7 @@ export function regenerateIntegrations(projectPath, manifest) {
   // Regenerate universal AGENTS.md if enabled and not already covered
   if (manifest.generateAgentsMd && !generatedFiles.has('AGENTS.md')) {
     const summaryConfig = {
-      installedStandards: installedStandardsList,
+      installedStandards: (manifest.standards || []).map(s => basename(s)),
       language: manifest.options?.display_language || 'en',
       outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english',
       standardOptions: manifest.options || {}
@@ -1422,7 +1418,7 @@ export function regenerateIntegrations(projectPath, manifest) {
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
  */
-async function updateIntegrationsOnly(projectPath, manifest) {
+async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   const msg = t().commands.update;
 
   console.log(chalk.cyan(msg.updatingIntegrationsOnly));
@@ -1436,6 +1432,59 @@ async function updateIntegrationsOnly(projectPath, manifest) {
     return;
   }
 
+  // --plan：只比對、不寫任何檔（連 manifest 也不寫）。
+  // 這一段刻意不呼叫 regenerateIntegrations——那個函式會寫檔，
+  // 「先寫再還原」的作法在中途掛掉時會留下壞狀態，比沒有 dry-run 更糟。
+  if (options.plan) {
+    console.log(chalk.bold('=== Integration Plan (dry run — nothing is written) ==='));
+    const wouldChange = [];
+    const unchanged = [];
+    const seen = new Set();
+    for (const tool of aiTools) {
+      const targetFile = getToolFilePath(tool);
+      if (seen.has(targetFile)) continue;
+      seen.add(targetFile);
+      const savedMode = manifest.contentMode || 'auto';
+      const resolvedMode = resolveContentModeForTool(tool, savedMode);
+      const next = generateIntegrationContent({
+        tool,
+        categories: ['anti-hallucination', 'commit-standards', 'code-review'],
+        language: (manifest.options?.output_language || manifest.options?.commit_language) === 'bilingual'
+          ? 'bilingual'
+          : (manifest.options?.output_language || manifest.options?.commit_language) === 'traditional-chinese'
+            ? 'zh-tw' : 'en',
+        installedStandards: manifest.standards?.map((x) => basename(x)) || [],
+        contentMode: resolvedMode.contentMode,
+        level: resolvedMode.level,
+        outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english'
+      });
+      const full = join(projectPath, targetFile);
+      const current = existsSync(full) ? readFileSync(full, 'utf8') : '';
+      const format = targetFile.endsWith('.md') ? 'markdown' : 'plaintext';
+      const cur = extractMarkedContent(current, format).content || '';
+      // 比對正規化過的內容：只關心「受管區塊會不會變」，不關心尾端空白。
+      if (cur.trim() === String(next).trim()) {
+        unchanged.push(targetFile);
+      } else {
+        const delta = String(next).trim().length - cur.trim().length;
+        wouldChange.push(`${targetFile} (${delta >= 0 ? '+' : ''}${delta} bytes in the UDS block)`);
+      }
+    }
+    if (wouldChange.length > 0) {
+      console.log(chalk.yellow(`  ~ Would update (${wouldChange.length}):`));
+      for (const f of wouldChange) console.log(chalk.gray(`      ${f}`));
+    }
+    if (unchanged.length > 0) {
+      console.log(chalk.gray(`  = Unchanged (${unchanged.length}): ${unchanged.join(', ')}`));
+    }
+    console.log();
+    console.log(chalk.gray('  Also NOT written in plan mode: .standards/manifest.json'));
+    console.log(chalk.gray('  (a real run rewrites it — version, fileHashes, integrationBlockHashes,'));
+    console.log(chalk.gray('   and it normalises any standards entries stored as full paths)'));
+    console.log();
+    return;
+  }
+
   const spinner = ora(msg.regeneratingIntegrations).start();
 
   // Use reusable regeneration function
@@ -1698,6 +1747,7 @@ async function updateSkillsOnly(projectPath, manifest, options) {
   // Update manifest
   manifest.skills.version = latestVersion;
   manifest.skills.installations = skillsInstallations;
+  manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
 
   // Update skill hashes for integrity tracking
   if (result.allFileHashes) {
@@ -1804,6 +1854,7 @@ async function updateCommandsOnly(projectPath, manifest, options) {
     }
     return inst;
   });
+  manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
 
   // Update command hashes for integrity tracking
   if (result.allFileHashes) {