universal-dev-standards 6.10.0 → 6.12.0

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

@@ -1,8 +1,8 @@
 ---
 source: ../../../docs/CLI-INIT-OPTIONS.md
-source_version: 3.5.1
-translation_version: 3.5.1
-last_synced: 2026-01-15
+source_version: 3.5.2
+translation_version: 3.5.2
+last_synced: 2026-09-18
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../docs/CLI-INIT-OPTIONS.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CLI-INIT-OPTIONS.md)
 >
-> **版本**: 3.5.0
-> **最後更新**: 2026-01-09
+> **版本**: 3.5.2
+> **最後更新**: 2026-09-18
 
 本文件詳細說明 `uds init` 命令的每一個選項，包含使用情境、影響範圍和建議選擇。
 
@@ -835,8 +835,49 @@ uds init --experimental
 | 不生成 AGENTS.md | `--no-agents-md` | 跳過 AGENTS.md 生成 |
 | 強制執行 Hooks | `--with-hooks` | 安裝強制執行 hooks（commit-msg、security、logging） |
 | 內容佈局 | `--content-layout` | 內容佈局（`flat`、`layered`）- 預設：`flat` |
+| Claude Code 目標檔 | `--claude-target` | Claude Code 整合內容要寫到哪裡：`project`（`CLAUDE.md`，預設）或 `local`（`CLAUDE.local.md`） |
 | 模式（已棄用） | `-m, --mode` | 安裝模式（skills, full）- 請改用 `--skills-location` |
 
+### Claude Code 整合目標檔（`--claude-target`）
+
+UDS 預設把 Claude Code 內容寫進 `CLAUDE.md`——團隊共用、會進版控的那個檔案。
+若你是在一個**已有團隊 `CLAUDE.md`** 的 repo 裡**個人採用** UDS，改用
+`--claude-target local`：UDS 會改寫入 `CLAUDE.local.md`，這是
+[Claude Code 原生支援](https://code.claude.com/docs/en/memory.md)、
+緊接在 `CLAUDE.md` 之後讀入的檔案，且完全不動團隊的檔案。
+
+```bash
+# 在有團隊 CLAUDE.md 的 repo 裡個人採用
+uds init -y --claude-target local
+```
+
+使用前有三件事要知道：
+
+1. **要自己把它加進 gitignore。** UDS 不會寫 `.gitignore` 或
+   `.git/info/exclude`——請自行把 `CLAUDE.local.md` 加進其中一個，
+   否則它會像任何新檔案一樣被 commit。
+2. **只存在於建立它的那個 worktree。** 因為（你 gitignore 之後）它是未受版控的檔案，
+   在某個 `git worktree` 建立的 `CLAUDE.local.md` 在同一個 repo 的另一個 worktree
+   看不到——每個 worktree 有自己的工作目錄，未受版控的檔案不會在 worktree 之間共享。
+   若你使用多個 worktree，需要在每一個裡分別執行
+   `uds init --claude-target local`（或下方的 `uds update --claude-target local`）。
+3. **`AGENTS.md` 不受影響。** `--claude-target` 只改變 Claude Code 內容要寫到哪裡。
+   若 `--agents-md` 生成了通用的 `AGENTS.md` 摘要，它仍照常寫進 `AGENTS.md`；
+   若也不想讓它進版控，一樣要自己排除（例如透過 `.git/info/exclude`）。
+
+已經用預設目標檔裝好了，想不重裝就切換？`uds update` 支援同一個旗標：
+
+```bash
+# 把既有安裝的 Claude Code 內容從 CLAUDE.md 搬到 CLAUDE.local.md
+uds update --claude-target local
+
+# 搬回去
+uds update --claude-target project
+```
+
+這會從舊檔移除 UDS 區塊（保留你自己寫在裡面的其他內容）、寫進新檔，並更新
+manifest——之後 `uds check` 驗的是新目標檔，不是舊的。
+
 ### 完整 CLI 範例
 
 ```bash
@@ -876,6 +917,12 @@ uds init -y --output-lang traditional-chinese --locale zh-tw
 
 # PHP 專案
 uds init -y --lang php --framework fat-free
+
+# 在有團隊 CLAUDE.md 的 repo 裡個人採用
+uds init -y --claude-target local
+
+# 之後把既有安裝切換到 CLAUDE.local.md，不需重裝
+uds update --claude-target local
 ```
 
 ---

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

@@ -1,7 +1,7 @@
 # UDS 功能參考手冊
 
 > Universal Development Standards - 完整功能文件
-> Auto-generated | Last updated: 2026-09-14
+> Auto-generated | Last updated: 2026-09-23
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
 
@@ -14,10 +14,10 @@
 3. [技能](#skills) (55)
 4. [代理](#agents) (5)
 5. [工作流程](#workflows) (5)
-6. [核心規範](#core-standards) (152)
+6. [核心規範](#core-standards) (153)
 7. [腳本](#scripts) (59)
 
-**Total Features: 350**
+**Total Features: 351**
 
 ---
 
@@ -54,6 +54,7 @@
 | `--no-agents-md` | Skip AGENTS.md generation |
 | `--with-hooks` | Install enforcement hooks declared by the installed standards |
 | `--content-layout` | Content layout (flat, layered) [default: flat] |
+| `--claude-target` | Claude Code integration target: project (default, writes CLAUDE.md) or local (writes CLAUDE.local.md — not committed to git; gitignore it yourself) |
 | `-y, --yes` | Use defaults, skip interactive prompts |
 | `-E, --experimental` | Enable experimental features (methodology) |
 | `--force` | Bypass UDS source-repo self-adoption guard (DEC-044 / XSPEC-071) |
@@ -155,6 +156,7 @@
 | `--force` | Force update all files, ignoring hash comparison |
 | `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
 | `--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 |
 
 ### `uds skills`
@@ -514,6 +516,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 |
 | `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 |  |

package/bundled/locales/zh-TW/integrations/claude-code/README.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../../integrations/claude-code/README.md
-source_version: 1.1.0
-translation_version: 1.1.0
-last_synced: 2026-08-12
+source_version: 1.2.0
+translation_version: 1.2.0
+last_synced: 2026-09-18
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: English | [繁體中文](README.md)
 
-**版本**: 1.1.0
-**最後更新**: 2026-08-12
+**版本**: 1.2.0
+**最後更新**: 2026-09-18
 
 本目錄包含將通用開發標準 (Universal Development Standards) 與 [Claude Code](https://docs.anthropic.com/claude-code) 整合的資源。
 
@@ -63,6 +63,15 @@ npx universal-dev-standards init
 2. 確保專案中存在 `core/` 目錄。
 3. 如有需要，安裝技能（請參閱 `skills/README.md`）。
 
+### 在已有團隊 `CLAUDE.md` 的 repo 裡個人採用（XSPEC-418）
+
+若 repo 已有進版控、團隊共用的 `CLAUDE.md`，而你要為自己個人採用 UDS，
+對 `init`（或 `update`，用於切換既有安裝）加上 `--claude-target local`，
+讓 UDS 改寫進 `CLAUDE.local.md`——Claude Code 會緊接在 `CLAUDE.md` 之後讀取它。
+你必須自己把 `CLAUDE.local.md` 加進 `.gitignore`（或 `.git/info/exclude`），
+且注意未受版控的檔案只存在於建立它的那個 git worktree。
+完整說明見 [CLI-INIT-OPTIONS.md § Claude Code 整合目標檔](../../../../docs/CLI-INIT-OPTIONS.md)。
+
 ## 驗證
 
 要驗證整合是否運作正常：

package/package.json

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

package/src/commands/check.js

@@ -12,7 +12,9 @@ import {
   computeFileHash,
   compareFileHash,
   hasFileHashes,
-  compareIntegrationBlockHash
+  compareIntegrationBlockHash,
+  computeIntegrationBlockHash,
+  pruneIntegrationFileHashes
 } from '../utils/hasher.js';
 import { downloadFromGitHub, getMarketplaceSkillsInfo } from '../utils/github.js';
 import {
@@ -30,7 +32,9 @@ import {
   findBrokenPathMentions,
   compareStandardsWithReferences
 } from '../utils/reference-sync.js';
-import { extractMarkedContent, getToolFilePath, parseStandardsIndexCount, writeIntegrationFile } from '../utils/integration-generator.js';
+import { extractMarkedContent, resolveIntegrationTargetFile, parseStandardsIndexCount, writeIntegrationFile } from '../utils/integration-generator.js';
+import { AmbiguousMarkerError } from '../utils/marker-locator.js';
+import { bumpManifestVersion } from '../core/manifest.js';
 import { INTEGRATION_MAPPINGS } from '../installers/integration-installer.js';
 import { getToolFormat } from '../core/constants.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
@@ -137,6 +141,19 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
   if (hasFileHashes(manifest)) {
     // Hash-based integrity check
     for (const [relativePath, hashInfo] of Object.entries(manifest.fileHashes)) {
+      // XSPEC-418 R6 gap 2: a manifest written before this fix can still
+      // carry a whole-file entry for a path that is ALSO tracked by its UDS
+      // block (integrationBlockHashes) — the pruning added for R6 only runs
+      // on a write (uds update / check --restore / --migrate), so a project
+      // that has not run one of those yet stayed red on `uds check --ci`
+      // forever, for content outside the block that the block check itself
+      // says is fine. This is a READ-time skip — it does not touch the
+      // manifest, so a plain `uds check` alone cannot fix the underlying
+      // stale entry; the write paths still do that (see
+      // pruneIntegrationFileHashes in hasher.js).
+      if (manifest.integrationBlockHashes && relativePath in manifest.integrationBlockHashes) {
+        continue;
+      }
       const fullPath = join(projectPath, relativePath);
       const status = compareFileHash(fullPath, hashInfo);
 
@@ -401,12 +418,38 @@ export async function checkCommand(options = {}) {
   // Check Commands integrity if commandHashes exist
   checkCommandsIntegrity(manifest, projectPath, msg);
 
+  // XSPEC adopter-report Q3: neither of the two checks above (content-hash
+  // integrity) says anything about an installed Skills/Commands version
+  // being behind the latest UDS release — that was only ever computed by
+  // `uds update --plan --skills`/`--commands`. A plain `uds check` gave no
+  // signal at all that `uds update --skills` had anything to do.
+  checkSkillsCommandsVersionStaleness(manifest, projectPath, msg);
+
   // Check Integration blocks integrity if integrationBlockHashes exist
-  checkIntegrationBlocksIntegrity(manifest, projectPath, msg);
+  // XSPEC-418 R1: the return value used to be discarded, so a removed/modified
+  // UDS block never affected the final verdict below — `uds check --ci` printed
+  // "compliant" and exited 0 with a visible ✗ still on screen.
+  const integrationBlockStatus = checkIntegrationBlocksIntegrity(manifest, projectPath, msg);
 
   // Handle --restore option
   if (options.restore) {
-    await restoreFiles(projectPath, manifest, [...fileStatus.modified, ...fileStatus.missing]);
+    // XSPEC-418 R6 gap 1: integration files no longer live in `fileHashes`
+    // at all (that was the point of R6), so `fileStatus` — built entirely
+    // from `fileHashes` — never contains them any more. Without this,
+    // `--restore` silently did nothing for a damaged UDS block: it
+    // regenerated zero files and printed "Restored 0 file(s)" while the
+    // block-modified/markers-removed content sat untouched.
+    // `restoreSingleFile`'s integration-file branch (`manifest.integrationConfigs`)
+    // does not depend on fileHashes, so feeding these paths in is enough —
+    // it already regenerates just the block and leaves everything else alone.
+    const integrationFilesToRestore = [
+      ...integrationBlockStatus.modified,
+      ...integrationBlockStatus.noMarkers,
+      ...integrationBlockStatus.missing
+    ];
+    await restoreFiles(projectPath, manifest, [
+      ...new Set([...fileStatus.modified, ...fileStatus.missing, ...integrationFilesToRestore])
+    ]);
     return;
   }
 
@@ -470,8 +513,15 @@ export async function checkCommand(options = {}) {
   displayWorkflowStatus(projectPath);
 
   // Final status
+  // XSPEC-418 R1: integration block problems (UDS markers removed, block
+  // modified, or the tracked file missing) now feed the verdict — they used to
+  // be checked and printed above, then silently dropped here.
   const allGood = fileStatus.missing.length === 0 &&
-                  fileStatus.modified.length === 0;
+                  fileStatus.modified.length === 0 &&
+                  integrationBlockStatus.modified.length === 0 &&
+                  integrationBlockStatus.missing.length === 0 &&
+                  integrationBlockStatus.noMarkers.length === 0 &&
+                  integrationBlockStatus.ambiguous.length === 0;
   if (allGood) {
     console.log(chalk.green(msg.projectCompliant));
   } else {
@@ -584,6 +634,11 @@ async function interactiveMode(projectPath, manifest, fileStatus, msg) {
   }
 
   if (manifestUpdated) {
+    // XSPEC-418 R6: interactive mode still has a "keep current content" branch
+    // that calls the whole-file updateFileHash(); if issue.file happens to be
+    // an integration file left in fileHashes by an older CLI, this is the
+    // write point that stops it from surviving another round.
+    pruneIntegrationFileHashes(manifest);
     writeManifest(manifest, projectPath);
     console.log(chalk.green(msg.manifestUpdated));
     console.log();
@@ -701,6 +756,9 @@ async function restoreFiles(projectPath, manifest, files) {
   }
 
   // Update manifest
+  // XSPEC-418 R6: catches any stale whole-file entry for an integration file
+  // this particular restore run didn't touch, not just the ones it did.
+  pruneIntegrationFileHashes(manifest);
   writeManifest(manifest, projectPath);
   console.log(chalk.gray(`  ${msg.manifestUpdatedShort}`));
   console.log();
@@ -728,7 +786,13 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
       installedStandards: genConfig.installedStandards || manifest.standards || []
     }, projectPath);
     if (result.success) {
-      updateFileHash(projectPath, manifest, relativePath);
+      // XSPEC-418 R6: this rewrites the UDS block, so the BLOCK hash is what
+      // must be refreshed — not a whole-file hash. Restoring used to call
+      // updateFileHash() here, which recorded the whole file (block +
+      // whatever the adopter wrote outside it) while leaving the stale block
+      // hash untouched; the next `uds check` then reported "UDS block
+      // modified" for a block that had just been correctly restored.
+      updateIntegrationBlockHash(manifest, relativePath, result.blockHashInfo);
       console.log(chalk.green(`  ✓ ${relativePath}: ${msg.restored}`));
       return true;
     }
@@ -750,7 +814,32 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
     // Integration file - copy to root
     const result = await copyIntegration(sourcePath, relativePath, projectPath);
     if (result.success) {
-      updateFileHash(projectPath, manifest, relativePath);
+      // XSPEC-418 R6: same rule as the genConfig branch above — track the
+      // block, not the whole file. This legacy static-copy fallback has no
+      // blockHashInfo returned to it, so compute one from what was just
+      // written; a template with no UDS markers at all (computeIntegration
+      // BlockHash returns null) falls back to the old whole-file behaviour,
+      // since there is no block to track instead.
+      // XSPEC adopter-report Q5: the file was just overwritten wholesale by
+      // copyIntegration (a full template copy, not a marker-preserving
+      // merge), so an ambiguous marker pair here cannot be this restore's
+      // own doing — fall back to whole-file hashing rather than fail a
+      // restore that already succeeded on disk.
+      let blockHashInfo;
+      try {
+        blockHashInfo = computeIntegrationBlockHash(join(projectPath, relativePath));
+      } catch (error) {
+        if (error instanceof AmbiguousMarkerError) {
+          blockHashInfo = null;
+        } else {
+          throw error;
+        }
+      }
+      if (blockHashInfo) {
+        updateIntegrationBlockHash(manifest, relativePath, blockHashInfo);
+      } else {
+        updateFileHash(projectPath, manifest, relativePath);
+      }
       console.log(chalk.green(`  ✓ ${relativePath}: ${msg.restored}`));
       return true;
     } else {
@@ -770,6 +859,30 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
   }
 }
 
+/**
+ * Update an integration file's UDS BLOCK hash in the manifest — not its
+ * whole-file hash (XSPEC-418 R6). Also drops any whole-file `fileHashes`
+ * entry for the same path, so restoring an integration file can never leave
+ * both records behind at once.
+ *
+ * @param {Object} manifest - Manifest object (mutated in place)
+ * @param {string} relativePath - Path as UDS reports it
+ * @param {Object|null|undefined} blockHashInfo - `{ blockHash, blockSize, fullHash, fullSize }`,
+ *   e.g. from `writeIntegrationFile`'s result or `computeIntegrationBlockHash`
+ * @returns {boolean} Whether a block hash was recorded
+ */
+export function updateIntegrationBlockHash(manifest, relativePath, blockHashInfo) {
+  if (!blockHashInfo) return false;
+  const normalizedPath = relativePath.replace(/\\/g, '/');
+  if (!manifest.integrationBlockHashes) manifest.integrationBlockHashes = {};
+  manifest.integrationBlockHashes[normalizedPath] = {
+    ...blockHashInfo,
+    installedAt: new Date().toISOString()
+  };
+  if (manifest.fileHashes) delete manifest.fileHashes[normalizedPath];
+  return true;
+}
+
 /**
  * Update file hash in manifest
  */
@@ -918,21 +1031,54 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
     }
   }
 
-  // Process integrations
+  // Process integrations — tracked by their UDS BLOCK hash, not a whole-file
+  // hash (XSPEC-418 R6). This loop used to write the whole file into the same
+  // `fileHashes` map as standards/extensions above, which is the same defect
+  // as every other write site R6 fixes, just reached by `--migrate` instead
+  // of a normal update: any content the adopter had outside the block then
+  // read as "modified" by standards-file integrity, contradicting the block
+  // check in the same `uds check` run.
+  const integrationBlockHashes = { ...(manifest.integrationBlockHashes || {}) };
   for (const intEntry of manifest.integrations) {
     const int = resolveIntegrationFile(intEntry) || intEntry;
     const fullPath = join(projectPath, int);
 
-    const hashInfo = computeFileHash(fullPath);
-    if (hashInfo) {
-      fileHashes[int] = { ...hashInfo, installedAt: now };
+    // XSPEC adopter-report Q5: this is a read-only manifest migration over
+    // every tracked integration file at once — one file with an ambiguous
+    // marker pair must not abort migrating the rest. It is simply left
+    // without a block hash, same as a file with no markers at all; `uds
+    // check`'s own block-integrity pass (below) is what surfaces the
+    // ambiguity to the user, with line numbers.
+    let blockHashInfo;
+    try {
+      blockHashInfo = computeIntegrationBlockHash(fullPath);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        blockHashInfo = null;
+      } else {
+        throw error;
+      }
+    }
+    if (blockHashInfo) {
+      integrationBlockHashes[int] = { ...blockHashInfo, installedAt: now };
       count++;
+    } else {
+      // No UDS markers found (plaintext template with none, or a file the
+      // adopter fully rewrote) — fall back to whole-file tracking, same as
+      // before this fix, rather than silently tracking nothing.
+      const hashInfo = computeFileHash(fullPath);
+      if (hashInfo) {
+        fileHashes[int] = { ...hashInfo, installedAt: now };
+        count++;
+      }
     }
   }
 
   // Update manifest
   manifest.fileHashes = fileHashes;
-  manifest.version = '3.1.0';
+  manifest.integrationBlockHashes = integrationBlockHashes;
+  bumpManifestVersion(manifest);
+  pruneIntegrationFileHashes(manifest);
   writeManifest(manifest, projectPath);
 
   console.log(chalk.green(msg.migratedCount.replace('{count}', count)));
@@ -1220,7 +1366,9 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
   // verdict — the tools that share it are named on the line instead.
   const toolsByFile = new Map();
   for (const tool of manifest.aiTools) {
-    const file = getToolFilePath(tool);
+    // XSPEC-418 R3: check must inspect the actual target file (e.g. CLAUDE.local.md),
+    // not the tool's hardcoded default.
+    const file = resolveIntegrationTargetFile(tool, manifest);
     if (!file) continue;
     if (!toolsByFile.has(file)) toolsByFile.set(file, []);
     toolsByFile.get(file).push(tool);
@@ -1251,7 +1399,20 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
 
     // Check for standards index marker
     const format = getToolFormat(tool);
-    const { content: markedContent } = extractMarkedContent(content, format);
+    let markedContent;
+    try {
+      ({ content: markedContent } = extractMarkedContent(content, format));
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        // XSPEC adopter-report Q5: report explicitly with line numbers
+        // instead of guessing which marker pair is real, or silently
+        // treating the file as if it had no UDS block at all.
+        console.log(chalk.red(`  ✗ ${toolFile}: ${error.message}`));
+        hasIssues = true;
+        continue;
+      }
+      throw error;
+    }
     const hasStandardsIndex = markedContent.length > 0 ||
       content.includes('Standards Index') ||
       content.includes('Standards Compliance');
@@ -1607,6 +1768,59 @@ async function checkCliVersion(bundledVersion) {
 // Enhanced Integrity Check Functions (v3.3.0+)
 // ============================================================
 
+/**
+ * Warn when an installed Skills or Commands version is behind the latest
+ * UDS release. This is deliberately modeled on the existing top-level
+ * "Version: X → Y ⚠" row (see the `hasUpdate` check in the summary
+ * dashboard below) rather than on `checkIntegrationBlocksIntegrity`
+ * (XSPEC-418 R1): a version simply being behind the latest release is
+ * ambient, expected state until the adopter chooses to update — not a
+ * compliance defect the way a modified/missing/ambiguous UDS block is — so
+ * it is reported but, unlike a block problem, does not fail `--ci`.
+ *
+ * Skills staleness is read per-installation from what is actually on disk
+ * (`getInstalledSkillsInfoForAgent`), the same source `uds update --plan
+ * --skills` uses, because different agents/levels can be out of sync
+ * independently. Commands have no per-installation version on disk (only a
+ * file count), so Commands staleness is read from the one version the
+ * manifest itself records (`manifest.commands.version`).
+ * // implements XSPEC adopter-report Q3
+ *
+ * @param {Object} manifest
+ * @param {string} projectPath
+ * @param {Object} msg - Localized messages (unused today; kept for symmetry
+ *   with the other Enhanced Integrity Check functions, which all take one)
+ */
+function checkSkillsCommandsVersionStaleness(manifest, projectPath, msg) { // eslint-disable-line no-unused-vars
+  const repoInfo = getRepositoryInfo();
+  const latestVersion = repoInfo.skills.version;
+  const stale = [];
+
+  const skillsInstallations = (manifest.skills?.installations || []).filter((i) => i.level !== 'marketplace');
+  for (const inst of skillsInstallations) {
+    const info = getInstalledSkillsInfoForAgent(inst.agent, inst.level, projectPath);
+    const current = info?.version;
+    if (current && current !== latestVersion) {
+      stale.push(`${getAgentDisplayName(inst.agent)} (${inst.level}): Skills v${current} → v${latestVersion}`);
+    }
+  }
+
+  if (manifest.commands?.installed && (manifest.commands?.installations || []).length > 0) {
+    const current = manifest.commands.version;
+    if (current && current !== latestVersion) {
+      stale.push(`Commands: v${current} → v${latestVersion}`);
+    }
+  }
+
+  if (stale.length === 0) return;
+
+  for (const line of stale) {
+    console.log(chalk.yellow(`  ⚠ ${line}`));
+  }
+  console.log(chalk.gray('    Run `uds update --plan --skills` / `--commands` for details, then `--apply` to update.'));
+  console.log();
+}
+
 /**
  * Check Skills files integrity against stored hashes
  * @param {Object} manifest - Manifest object
@@ -1789,19 +2003,19 @@ export function checkCommandsIntegrity(manifest, projectPath, msg) {
  * @param {Object} manifest - Manifest object
  * @param {string} projectPath - Project root path
  * @param {Object} msg - Localized messages
- * @returns {Object} Status { unchanged: [], modified: [], missing: [], noMarkers: [] }
+ * @returns {Object} Status { unchanged: [], modified: [], missing: [], noMarkers: [], ambiguous: [] }
  */
 function checkIntegrationBlocksIntegrity(manifest, projectPath, msg) {
   const blockHashes = manifest.integrationBlockHashes;
 
   // Skip if no block hashes tracked
   if (!blockHashes || Object.keys(blockHashes).length === 0) {
-    return { unchanged: [], modified: [], missing: [], noMarkers: [], tracked: false };
+    return { unchanged: [], modified: [], missing: [], noMarkers: [], ambiguous: [], tracked: false };
   }
 
   console.log(chalk.cyan(msg.integrationBlocksCheck || 'Integration UDS Block Integrity'));
 
-  const status = { unchanged: [], modified: [], missing: [], noMarkers: [], tracked: true };
+  const status = { unchanged: [], modified: [], missing: [], noMarkers: [], ambiguous: [], tracked: true };
 
   for (const [filePath, hashInfo] of Object.entries(blockHashes)) {
     const fullPath = join(projectPath, filePath);
@@ -1813,7 +2027,21 @@ function checkIntegrationBlocksIntegrity(manifest, projectPath, msg) {
     }
 
     // Compare block hash
-    const blockStatus = compareIntegrationBlockHash(fullPath, hashInfo);
+    // XSPEC adopter-report Q5: a file with two real START or END marker
+    // lines is not "modified" and not "no markers" — it is ambiguous, and
+    // the whole point of this fix is to report that explicitly (with line
+    // numbers) instead of silently picking one and guessing.
+    let blockStatus;
+    try {
+      blockStatus = compareIntegrationBlockHash(fullPath, hashInfo);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        status.ambiguous.push(filePath);
+        console.log(chalk.red(`  ✗ ${filePath}: ${error.message}`));
+        continue;
+      }
+      throw error;
+    }
 
     switch (blockStatus) {
       case 'unchanged':
@@ -1835,17 +2063,21 @@ function checkIntegrationBlocksIntegrity(manifest, projectPath, msg) {
   }
 
   // Summary
-  if (status.modified.length === 0 && status.missing.length === 0 && status.noMarkers.length === 0) {
+  if (status.modified.length === 0 && status.missing.length === 0 && status.noMarkers.length === 0 && status.ambiguous.length === 0) {
     console.log(chalk.green(`  ✓ ${msg.allBlocksIntact || 'All UDS blocks intact'} (${status.unchanged.length} files)`));
     console.log(chalk.gray(`    ${msg.userContentPreserved || 'User customizations outside UDS blocks are preserved'}`));
   } else {
     console.log(chalk.gray(`  ${(msg.blocksIntegritySummary || '{unchanged} intact, {modified} modified, {missing} missing')
       .replace('{unchanged}', status.unchanged.length)
       .replace('{modified}', status.modified.length)
-      .replace('{missing}', status.missing.length + status.noMarkers.length)}`));
+      .replace('{missing}', status.missing.length + status.noMarkers.length + status.ambiguous.length)}`));
 
     if (status.modified.length > 0 || status.noMarkers.length > 0) {
-      console.log(chalk.yellow(`    ${msg.runUpdateIntegrations || 'Run "uds update --integrations-only" to restore UDS content'}`));
+      // XSPEC-418 R6 gap 1: `uds check --restore` now regenerates just the
+      // UDS block for these files too (it used to do nothing for them — see
+      // the --restore handler above), so it is named alongside `uds update
+      // --integrations-only` rather than as a second-choice remedy.
+      console.log(chalk.yellow(`    ${msg.runUpdateIntegrations || 'Run "uds check --restore" or "uds update --integrations-only" to restore UDS content'}`));
     }
   }
 

package/src/commands/config.js

@@ -45,11 +45,11 @@ import {
 import { displayLanguageToLocale } from '../utils/locale.js';
 import {
   writeIntegrationFile,
-  getToolFilePath
+  resolveIntegrationTargetFile
 } from '../utils/integration-generator.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import { regenerateIntegrations } from './update.js';
-import { mergeInstalledNames } from '../core/manifest.js';
+import { mergeInstalledNames, bumpManifestVersion } from '../core/manifest.js';
 
 /**
  * Get localized message with fallback (for config-specific keys)
@@ -667,13 +667,16 @@ export async function runProjectConfiguration(options) {
       // Remove integration files for removed tools
       const spinner = createSpinner(msgObj.removingIntegrations).start();
       for (const tool of result.tools) {
-        const filePath = join(projectPath, getToolFilePath(tool));
+        // XSPEC-418 R3: remove the file this tool actually targets (e.g.
+        // CLAUDE.local.md), not always its hardcoded default.
+        const removedToolFile = resolveIntegrationTargetFile(tool, manifest);
+        const filePath = join(projectPath, removedToolFile);
         if (existsSync(filePath)) {
           try {
             unlinkSync(filePath);
-            console.log(chalk.gray(`  ${msgObj.removed}: ${getToolFilePath(tool)}`));
+            console.log(chalk.gray(`  ${msgObj.removed}: ${removedToolFile}`));
           } catch {
-            console.log(chalk.yellow(`  ${msgObj.couldNotRemove}: ${getToolFilePath(tool)}`));
+            console.log(chalk.yellow(`  ${msgObj.couldNotRemove}: ${removedToolFile}`));
           }
         }
 
@@ -711,7 +714,7 @@ export async function runProjectConfiguration(options) {
         }
 
         // Remove from integrationBlockHashes (keyed by tool file path)
-        const toolFileName = getToolFilePath(tool);
+        const toolFileName = removedToolFile;
         if (manifest.integrationBlockHashes?.[toolFileName]) {
           delete manifest.integrationBlockHashes[toolFileName];
         }
@@ -934,7 +937,8 @@ export async function runProjectConfiguration(options) {
     const generatedFiles = new Set();
 
     for (const tool of newAITools) {
-      const targetFile = getToolFilePath(tool);
+      // XSPEC-418 R3
+      const targetFile = resolveIntegrationTargetFile(tool, manifest);
       if (generatedFiles.has(targetFile)) {
         continue; // Skip if already generated (AGENTS.md sharing)
       }
@@ -947,7 +951,9 @@ export async function runProjectConfiguration(options) {
         standardsFormat: manifest.format || 'ai',
         contentMode: newContentMode,
         // Pass output_language for dynamic commit standards generation
-        outputLanguage: newOptions.output_language || 'english'
+        outputLanguage: newOptions.output_language || 'english',
+        // XSPEC-418 R2/R3
+        integrationTargets: manifest.integrationTargets
       };
 
       const result = writeIntegrationFile(tool, toolConfig, projectPath);
@@ -1052,7 +1058,7 @@ export async function runProjectConfiguration(options) {
   manifest.options = newOptions;
   manifest.contentMode = newContentMode;
   manifest.aiTools = newAITools;
-  manifest.version = '3.2.0';
+  bumpManifestVersion(manifest);
 
   // Update methodology
   if (newMethodology) {