universal-dev-standards 6.10.0 → 6.11.0

package/bin/uds.js

@@ -138,6 +138,7 @@ program
   .option('--no-agents-md', 'Skip AGENTS.md generation')
   .option('--with-hooks', 'Install enforcement hooks declared by the installed standards')
   .option('--content-layout <layout>', 'Content layout (flat, layered) [default: flat]')
+  .option('--claude-target <target>', 'Claude Code integration target: project (default, writes CLAUDE.md) or local (writes CLAUDE.local.md — not committed to git; gitignore it yourself)')
   .option('-y, --yes', 'Use defaults, skip interactive prompts')
   .option('-E, --experimental', 'Enable experimental features (methodology)')
   .option('--force', 'Bypass UDS source-repo self-adoption guard (DEC-044 / XSPEC-071)')
@@ -228,6 +229,7 @@ program
   .option('--force', 'Force update all files, ignoring hash comparison')
   .option('--prune', 'Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write)')
   .option('--rollback', 'Rollback to the most recent backup')
+  .option('--claude-target <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')
   .option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')
   .action(updateCommand);
 

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

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.10.0
-translation_version: 6.10.0
-last_synced: 2026-09-16
+source_version: 6.11.0
+translation_version: 6.11.0
+last_synced: 2026-09-18
 status: current
 ---
 
@@ -17,6 +17,26 @@ status: current
 
 ## [Unreleased]
 
+## [6.11.0] - 2026-09-18
+
+### 修复
+
+- **`uds update --plan`／`--apply` 对整合文件永远不会收敛：即使刚跑完 `--apply`、文件内容与生成器会生成的内容逐字节相同，仍会显示 `Migrate Block: N`。** `diffIntegrations` 对任何带有 UDS 标记的整合文件都无条件产生 `migrate_block` 动作——"我们一律更新整合文件，因为内容是动态生成的"——因为 desired state 从未带有可比对的哈希（`hash: null`，注释说"生成后才计算"，但从未真正算过）。desired-state calculator 现在会用 `--apply` 自己会用的同一条路径（`buildToolIntegrationConfig` ＋ `generateIntegrationContent`）生成整合文件内容，并只对 UDS 区块算哈希，让 `diffIntegrations` 能像其他每个类别一样分辨"内容已经相符"与"内容不同"，哈希相符时报告 `unchanged` 而非 `migrate_block`。一份区块真的过期的文件（手动编辑过，或由旧版 CLI 生成）仍会照旧产生 `migrate_block`。生成失败（例如 registry 解不出某个工具）时回退为修正前的无条件行为，不会让计划崩溃。
+- **`uds check` 可能在同一次运行里对同一个整合文件打印两条互相矛盾的"已引用"宣告。** `standardsReferenced`（"已引用 {count}/{total} 项标准"）扫描整个整合文件正文——标准名称在任何地方被提到都算。`standardsNotReferenced`（"未引用的标准（可选）："）只看结构化的 `Reference:`／`参考:` 行。一个标准在文件散文中被提到、却没有列在任何 `Reference:` 行上，会在同一次运行里同时满足第一条宣告、又落在第二条宣告里——同一个词（"已引用"／"引用"），量测的是两件不同的事，读起来像矛盾。三语的第二条消息都已改写成精确描述它实际检查的内容（没有出现在 `Reference:`／`参考:` 行），取代原本笼统的"未引用"宣告。
+- **单纯的 `uds update --plan` 与 `uds check` 从未提示 Skills 或 Commands 版本落后最新 UDS 发行版。** 版本落后只由 `uds update --plan --skills`／`--plan --commands` 计算——一般的协调 `--plan`（不带范围标志）调用的是另一个从未触及这件事的函数，`uds check` 则完全没有对等的检查。用户跑纯粹的 `--plan` 或 `check` 时，看到的是一份干净的报告，尽管 Skills 落后了一整个小版本，也没有任何提示说带范围的 plan、或 `uds update --skills` 有事可做。两者现在都会在任何已安装的 Skills 或 Commands 版本落后时，打印简短的"`<工具>`（`<位置>`）：v旧 → v新"提示，并附上修复命令。这比照既有的顶层"Version: X → Y ⚠"行，而非整合区块完整性检查（XSPEC-418 R1）：落后最新版是用户更新前的常态，不是像 UDS 区块被修改／丢失那样的合规缺陷，因此不会让 `uds check --ci` 失败。
+- **6.10.0 的死链接修正（P2）把一条写着 6.0.0 之前文件名的引用直接删掉，而不是改写它，还可能留下一个悬空的逗号。** `resolveStandardReferences` 比对一行 `Reference:` 的 stem 时只查 manifest 已安装清单，从未查过 `STANDARD_ID_MAPPING`（conversion-rules.js）——这正是 `yaml-generator.js` 别处已在用、记录"旧文件名 → 现行 id"的对照表。一行写着旧文件名 `.standards/commit-message-guide.md` 而项目其实装了 `commit-message` 的引用，看起来和一个项目刻意不装、已停用的 UDS 标准一模一样，于是被整行删掉，而不是改写成 `.standards/commit-message.ai.yaml`。另外，删掉一项引用后的逗号清理只处理了尾部逗号、重复逗号、逗号前多余空格，没处理"一行里第一项引用被删掉、逗号紧贴在冒号后面"的状况（`Reference:, .standards/other.ai.yaml`）。整段改写为"拆项 → 解析或舍弃 → 重新 join"，取代在原地修补被删字符串周围标点的做法。
+- **被 6.10.0 `resolveStandardReferences` 缺陷删掉的主要标准引用，即使套用上面的修正也不会自己回来。** 把删除动作留下的悬空逗号清掉，修好的只是那一行的标点，不是把被删掉的项目带回来——像"## 提交讯息标准"这样的 UDS 模板段落活在 UDS 标记之外，一旦某一项被删掉，就没有任何东西会重新生成那段内容。针对这个特定情境新增一个范围刻意收窄的自动修复机制：当一行的标题与某个 UDS 模板标题完全相同（`RULE_TEMPLATES` 出货的任一语言版本），而且该模板的主要引用（它自己"`Reference:`"／"`參考:`"行上的第一个 `.standards/...` 项）不在文件那一行里，且该标准确实已安装，就会把它补回该行最前面——行内其他内容（项目自有条目、options 文件、既有顺序）原样不动，不会补回任何次要模板条目，用户自己写的段落（任何其他标题）一律不碰。此修复是幂等的。只修复 6.10.0 那次删除造成的问题，不尝试修复由无关手动编辑造成的引用损坏。
+- **单纯的 `uds update` 从未修复上面 Q1 缺陷留下的坏掉的 `integrationConfigs[file].categories`——只有 `--sync-refs` 会。** 一份已经带着 `categories: []`（来自较旧、有缺陷的 `--sync-refs` 运行）的 manifest，会在之后每一次单纯的 `uds update --yes` 都维持坏掉：该命令自己的整合同步步骤会写 `integrationBlockHashes`，却完全不会读取 `integrationConfigs`，所以没有任何东西修正它——而下一次 `uds check --restore-missing` 就会用那份坏掉的存储配置重建整合文件，再次悄悄漏掉段落。`uds update` 现在会用 `--sync-refs` 同样的方式（`calculateCategoriesFromStandards`）修复空的或无法识别的 `categories` 值，而已经有效的列表维持原样不动，让单纯的 update 不会每次都变成完整的重新同步。
+- **`uds update --sync-refs`／`--integrations-only`／`uds check --migrate`／`uds config` 可能悄悄把 `manifest.version` 降级，同一条同步路径还会在一份正常的 3.4.0 manifest 上算出空的分类集合。** 五个写入点写死了一个较旧的 schema 版本字面值（`'3.1.0'`／`'3.2.0'`／`'3.3.0'`），而不是 CLI 当前的 schema 版本（`3.4.0`）——对一份已经是最新版的 manifest 执行上述任一命令，都会把版本写回旧的。另外，`calculateCategoriesFromStandards`（`--sync-refs` 用来决定 CLAUDE.md／AGENTS.md 该含哪些段落的函数）用文件名查每个标准，但 3.4.0 manifest 存的是纯 stem（`commit-message`，而非 `commit-message.ai.yaml`）——每次查询都落空，分类集合变成空的，下一次 `--sync-refs`（或 `--restore-missing` 重建）就会重新生成一份完全漏掉反幻觉／commit-message／code-review 段落的文件。两者现在都在同一个真实来源处修复：一个共用的 `bumpManifestVersion` 辅助函数，只会让 manifest 版本朝最新前进，不会倒退；以及同文件里别处已在用、支持 stem 的分类查找（`categoryForStandard`）。这让分类计算恢复成 `--sync-refs` 在 6.10.0 之前的算法——依实际已安装的标准计算，而非固定列表——所以完整重新生成（`--sync-refs`、`--integrations-only`，或单纯的 `uds update`）现在会写出每一个有模板、且背后有已安装标准的段落（目前 9 段），而不只是全新 `uds init` 播种的那 3 段；对一个已经有完整段落的项目做纯区块更新则不受影响。
+- **一句单纯提到 UDS 标记文字的句子，可能被误认成真正的区块边界，导致从那句话到真正 END 标记之间的所有内容——包含采用者自己的内容——都被删除（v3.5.0–6.10.0）。** 每一个定位标记的调用点都直接用 `content.indexOf('<!-- UDS:STANDARDS:START -->')`／`.indexOf('...:END -->')`，这会匹配到文件中任何位置出现的标记文字：一句逐字引用标记语法来解释它的句子（本项目自己的 CLAUDE.md 就是这样做），或代码区块里含有它的示例，都和真正的边界无从分辨。这影响了所有四条会重新生成整合文件 UDS 区块的写入路径：`uds update --integrations-only`、`uds update --apply` 的 `migrate_block` reconciler 路径、`uds update --sync-refs`，以及 `uds check --restore`（XSPEC-418 R6 让它也会恢复受损的 UDS 区块）。标记现在只在（去除首尾空白后）独占一整行、且那一行不在 fenced code block（``` ／ ~~~）内时才算数；所有调用点现在都经过同一个共用的 `locateMarkerBlock` 辅助函数，并以静态扫描守卫测试强制执行，避免未来的调用点又退回直接用 `indexOf`／`includes`。含有两组真正标记对的文件（损坏，或手动编辑出错）不再被猜测——每条写入路径都会拒绝执行并列出两个标记所在行号，`uds check` 也会明确报告这个状态，不再并入"已修改"或"找不到标记"。
+- **`uds check --ci` 可能画面上打印整合区块的 ✗，结尾却仍宣称项目符合标准并以退出码 0 收尾。** `checkIntegrationBlocksIntegrity` 的检查结果（区块被修改／丢失／UDS 标记被移除）算出来也打印出来了，却在最终判定被丢弃——判定只看标准文件完整性。若你的 CI 一直对某个 CLAUDE.md／GEMINI.md 等文件的 UDS 区块实际上已被移除或改动的项目显示绿灯，那就是这个缺陷；`--ci` 现在会正确地失败，直到区块被恢复（`uds update --integrations-only`）或项目以其他方式恢复同步为止。交互式 `uds check`（不加 `--ci`）不受影响——仍以退出码 0 收尾，不中断一般使用。（XSPEC-418 R1）
+- **整合文件（CLAUDE.md、CLAUDE.local.md、AGENTS.md 等）同时被整份内容与 UDS 区块两套哈希追踪，两套检查在同一次运行里可能互相矛盾。** 全新 `uds init` 从不为这些文件记录整份哈希，但 `uds update --integrations-only` 会——跑过一次之后，用户在 UDS 区块**外**的任何修改（正是 marker-based update 承诺保留的自定义内容）都会让 `uds check --ci` 报 `CLAUDE.md（已修改）` 并退出码 1，而同一次输出里自己的区块完整性检查却说区块完好。另外，`uds check --restore` 正确地重写了损坏的区块（保留区块外内容，没有数据丢失），却只更新了整份哈希，从未更新区块哈希——于是下一次 check 对一个刚被正确恢复的区块报 `CLAUDE.md（UDS 区块已修改）`。整合文件现在不再写入 `fileHashes`（只写入本来就只追踪区块的 `integrationBlockHashes`）——走查了所有写入点，不只最初报告的两处，包括 `--apply`／`--plan` 的 reconciler 路径与 `--sync-refs`；已有 manifest 里这类文件残留的整份哈希，会在下一次 `uds update`（或 `uds check --restore`／`--migrate`）时被移除，区块哈希保留。`uds check --restore` 恢复整合文件后，现在会把区块哈希更新为实际写入的内容。已用一份真实采用者的 manifest（恰好带有这个残留字段）验证：同一份输入，修正前 `uds check --ci` 退出码 1，修正后退出码 0。后续复核另发现两个缺口，一并修掉：`uds check --restore` 过去对受损的 UDS 区块完全无作用——它靠的是 `fileStatus`，而那完全由 `fileHashes` 构建，已不含整合文件，于是它悄悄恢复了 0 个文件而区块仍是坏的；`--restore` 现在也会恢复被判定为「已修改」或「标记丢失」的区块（不动区块外内容，`--restore-missing` 行为不变）。另外，因为上面新增的清除逻辑只挂在写入路径，已有 manifest 里残留的整份哈希若不曾跑过写入，纯 `check` 永远没有机会清掉它——标准文件完整性检查现在也会在读取时跳过同时被 `integrationBlockHashes` 追踪的键，让未跑过 `update` 的已有项目也能报告干净。（XSPEC-418 R6）
+
+### 新增
+
+- **`uds init --claude-target <project|local>` 与 `uds update --claude-target <project|local>`：在已有团队 `CLAUDE.md` 的仓库里个人采用 UDS。** 过去 UDS 的 Claude Code 集成一律写入 `CLAUDE.md`——团队共用、会进版本控制的文件——没有任何改写目标的方式。在已有团队 `CLAUDE.md` 的仓库里个人采用 UDS 的用户，只能手动把 UDS 区块移到 `CLAUDE.local.md`（Claude Code 原生支持、紧接在 `CLAUDE.md` 之后读入的文件），而从那一刻起 `check`／`update`／`uninstall` 全都报告错误，或悄悄写回团队文件——包括在例行孤儿清理中把移动后文件自己的哈希当作"孤儿"删除。
+  `uds init` 的 `--claude-target local` 从一开始就把集成内容写进 `CLAUDE.local.md`；团队的 `CLAUDE.md` 完全不会被动到。`uds update --claude-target <project|local>` 则让**已有**安装不必重装就能切换目标：从旧文件移除 UDS 区块（保留写在里面的其他内容；若旧文件在移除后只剩 UDS 内容则整个删除，与 `uninstall` 既有规则一致）、写入新目标、并更新 manifest，不论新目标是否已存在手动移过去的区块。`check`、`update`（含 `--integrations-only`／`--force`）与孤儿哈希清理现在都经同一个函数解出工具的实际目标文件，不再各自假设默认值——从未使用 `--claude-target` 的项目完全不受影响：manifest 只有在选择 `local` 时才会多出 `integrationTargets` 字段。`--claude-target` 不影响 `AGENTS.md`；若不想让它进版本控制，一样要自己通过 `.git/info/exclude` 排除。UDS 不会自动把 `CLAUDE.local.md` 写进 `.gitignore`——请自行加入——且因为它未受版本控制，只存在于创建它的那个 git worktree。详见 [CLI-INIT-OPTIONS.md](docs/CLI-INIT-OPTIONS.md)（"Claude Code 集成目标文件"一节）。（XSPEC-418 R2–R4）
+
 ## [6.10.0] - 2026-09-16
 
 ### 修复

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

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

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

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支持状态 |
 |------|--------|
-| 6.10.0 | ✅ 最新正式版 |
+| 6.11.0 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-CN/docs/CHEATSHEET.md

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-09-14
+> Quick reference for all UDS features | Last updated: 2026-09-18
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
 

package/bundled/locales/zh-CN/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-TW/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`** 的仓库里**个人采用** UDS，改用
+`--claude-target local`：UDS 会改写入 `CLAUDE.local.md`，这是
+[Claude Code 原生支持](https://code.claude.com/docs/en/memory.md)、
+紧接在 `CLAUDE.md` 之后读入的文件，且完全不动团队的文件。
+
+```bash
+# 在有团队 CLAUDE.md 的仓库里个人采用
+uds init -y --claude-target local
+```
+
+使用前有三件事要知道：
+
+1. **要自己把它加进 gitignore。** UDS 不会写 `.gitignore` 或
+   `.git/info/exclude`——请自行把 `CLAUDE.local.md` 加进其中一个，
+   否则它会像任何新文件一样被提交。
+2. **只存在于创建它的那个 worktree。** 因为（你 gitignore 之后）它是未受版本控制的文件，
+   在某个 `git worktree` 创建的 `CLAUDE.local.md` 在同一个仓库的另一个 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-cn
 
 # PHP 项目
 uds init -y --lang php --framework fat-free
+
+# 在有团队 CLAUDE.md 的仓库里个人采用
+uds init -y --claude-target local
+
+# 之后把已有安装切换到 CLAUDE.local.md，不需要重装
+uds update --claude-target local
 ```
 
 ---

package/bundled/locales/zh-CN/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-18
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
 
@@ -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`

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

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.10.0
-translation_version: 6.10.0
-last_synced: 2026-09-16
+source_version: 6.11.0
+translation_version: 6.11.0
+last_synced: 2026-09-18
 status: current
 ---
 
@@ -17,6 +17,26 @@ status: current
 
 ## [Unreleased]
 
+## [6.11.0] - 2026-09-18
+
+### 修正
+
+- **`uds update --plan`／`--apply` 對整合檔永遠不會收斂：即使剛跑完 `--apply`、檔案內容與產生器會產生的內容逐位元組相同，仍會顯示 `Migrate Block: N`。** `diffIntegrations` 對任何帶有 UDS 標記的整合檔都無條件產生 `migrate_block` 動作——「我們一律更新整合檔，因為內容是動態產生的」——因為 desired state 從未帶有可比對的雜湊（`hash: null`，註解說「產生後才計算」，但從未真的算過）。desired-state calculator 現在會用 `--apply` 自己會用的同一條路徑（`buildToolIntegrationConfig` ＋ `generateIntegrationContent`）產生整合檔內容，並只對 UDS 區塊算雜湊，讓 `diffIntegrations` 能像其他每個類別一樣分辨「內容已經相符」與「內容不同」，雜湊相符時回報 `unchanged` 而非 `migrate_block`。一份區塊真的過期的檔案（手動編輯過，或由舊版 CLI 產生）仍會照舊產生 `migrate_block`。產生失敗（例如 registry 解不出某個工具）時回退成修正前的無條件行為，不會讓計畫當掉。
+- **`uds check` 可能在同一次執行裡對同一個整合檔印出兩則互相矛盾的「已參考」宣告。** `standardsReferenced`（「{count}/{total} 項標準已參考」）掃描整個整合檔本文——標準名稱在任何地方被提到都算。`standardsNotReferenced`（「未參考的標準（選用）：」）只看結構化的 `Reference:`／`參考:` 行。一個標準在檔案散文中被提到、卻沒有列在任何 `Reference:` 行上，會在同一次執行裡同時滿足第一則宣告、又落在第二則宣告裡——同一個詞（「已參考」／「參考」），量測的是兩件不同的事，讀起來像矛盾。三語的第二則訊息都已改寫成精確描述它實際檢查的內容（沒有出現在 `Reference:`／`參考:` 行），取代原本籠統的「未參考」宣告。
+- **單純的 `uds update --plan` 與 `uds check` 從未提示 Skills 或 Commands 版本落後最新 UDS 釋出版。** 版本落後只由 `uds update --plan --skills`／`--plan --commands` 計算——一般的調和 `--plan`（不帶範圍旗標）呼叫的是另一個從未碰觸這件事的函式，`uds check` 則完全沒有對等的檢查。使用者跑純粹的 `--plan` 或 `check` 時，看到的是一份乾淨的報告，儘管 Skills 落後了一整個小版本，也沒有任何提示說帶範圍的 plan、或 `uds update --skills` 有事可做。兩者現在都會在任何已安裝的 Skills 或 Commands 版本落後時，印出簡短的「`<工具>`（`<位置>`）：v舊 → v新」提示，並附上修復指令。這比照既有的頂層「Version: X → Y ⚠」列，而非整合區塊完整性檢查（XSPEC-418 R1）：落後最新版是使用者更新前的常態，不是像 UDS 區塊被修改／遺失那樣的合規缺陷，因此不會讓 `uds check --ci` 失敗。
+- **6.10.0 的死連結修正（P2）把一則寫著 6.0.0 之前檔名的參考直接刪掉，而不是改寫它，還可能留下一個懸空的逗號。** `resolveStandardReferences` 比對一行 `Reference:` 的 stem 時只查 manifest 已安裝清單，從未查過 `STANDARD_ID_MAPPING`（conversion-rules.js）——這正是 `yaml-generator.js` 別處已在用、記錄「舊檔名 → 現行 id」的對照表。一行寫著舊檔名 `.standards/commit-message-guide.md` 而專案其實裝了 `commit-message` 的參考，看起來和一個專案刻意不裝、已停用的 UDS 標準一模一樣，於是被整行刪掉，而不是改寫成 `.standards/commit-message.ai.yaml`。另外，刪掉一項參考後的逗號清理只處理了尾端逗號、重複逗號、逗號前多餘空白，沒處理「一行裡第一項參考被刪掉、逗號緊貼在冒號後面」的狀況（`Reference:, .standards/other.ai.yaml`）。整段改寫成「拆項 → 解析或捨棄 → 重新 join」，取代在原地修補被刪字串周圍標點的作法。
+- **被 6.10.0 `resolveStandardReferences` 缺陷刪掉的主要標準參考，即使套用上面的修正也不會自己回來。** 把刪除動作留下的懸空逗號清掉，修好的只是那一行的標點，不是把被刪掉的項目帶回來——像「## 提交訊息標準」這樣的 UDS 範本段落活在 UDS 標記之外，一旦某一項被刪掉，就沒有任何東西會重新產生那段內容。針對這個特定情境新增一個範圍刻意收窄的自動補回機制：當一行的標題與某個 UDS 範本標題完全相同（`RULE_TEMPLATES` 出貨的任一語言版本），而且該範本的主要參考（它自己「`Reference:`」／「`參考:`」行上的第一個 `.standards/...` 項）不在檔案那一行裡，且該標準確實已安裝，就會把它補回該行最前面——行內其他內容（專案自有項目、options 檔、既有順序）原樣不動，不會補回任何次要範本項目，使用者自己寫的段落（任何其他標題）一律不碰。此修復是冪等的。只修復 6.10.0 那次刪除造成的問題，不嘗試修復由無關手動編輯造成的參考損壞。
+- **單純的 `uds update` 從未修復上面 Q1 缺陷留下的壞掉 `integrationConfigs[file].categories`——只有 `--sync-refs` 會。** 一份已經帶著 `categories: []`（來自較舊、有缺陷的 `--sync-refs` 執行）的 manifest，會在之後每一次單純的 `uds update --yes` 都維持壞掉：該指令自己的整合同步步驟會寫 `integrationBlockHashes`，卻完全不會讀取 `integrationConfigs`，所以沒有任何東西修正它——而下一次 `uds check --restore-missing` 就會用那份壞掉的儲存設定重建整合檔，再次悄悄漏掉段落。`uds update` 現在會用 `--sync-refs` 同樣的方式（`calculateCategoriesFromStandards`）修復空的或無法辨識的 `categories` 值，而已經有效的清單維持原樣不動，讓單純的 update 不會每次都變成完整的重新同步。
+- **`uds update --sync-refs`／`--integrations-only`／`uds check --migrate`／`uds config` 可能悄悄把 `manifest.version` 降版，同一條同步路徑還會在一份正常的 3.4.0 manifest 上算出空的分類集合。** 五個寫入點寫死了一個較舊的 schema 版本字面值（`'3.1.0'`／`'3.2.0'`／`'3.3.0'`），而不是 CLI 目前的 schema 版本（`3.4.0`）——對一份已經是最新版的 manifest 執行上述任一指令，都會把版本寫回舊的。另外，`calculateCategoriesFromStandards`（`--sync-refs` 用來決定 CLAUDE.md／AGENTS.md 該含哪些段落的函式）用檔名查每個標準，但 3.4.0 manifest 存的是純 stem（`commit-message`，而非 `commit-message.ai.yaml`）——每次查詢都落空，分類集合變成空的，下一次 `--sync-refs`（或 `--restore-missing` 重建）就會重新產生一份完全漏掉反幻覺／commit-message／code-review 段落的檔案。兩者現在都在同一個真實來源處修復：一個共用的 `bumpManifestVersion` 輔助函式，只會讓 manifest 版本朝最新前進，不會倒退；以及同檔案裡別處已在用、支援 stem 的分類查找（`categoryForStandard`）。這讓分類計算恢復成 `--sync-refs` 在 6.10.0 之前的算法——依實際已安裝的標準計算，而非固定清單——所以完整重新產生（`--sync-refs`、`--integrations-only`，或單純的 `uds update`）現在會寫出每一個有範本、且背後有已安裝標準的段落（目前 9 段），而不只是全新 `uds init` 播種的那 3 段；對一個已經有完整段落的專案做純區塊更新則不受影響。
+- **一句單純提到 UDS 標記文字的句子，可能被誤認成真正的區塊邊界，導致從那句話到真正 END 標記之間的所有內容——包含採用者自己的內容——都被刪除（v3.5.0–6.10.0）。** 每一個定位標記的呼叫點都直接用 `content.indexOf('<!-- UDS:STANDARDS:START -->')`／`.indexOf('...:END -->')`，這會比對到檔案中任何位置出現的標記文字：一句逐字引用標記語法來解釋它的句子（本專案自己的 CLAUDE.md 就是這樣做），或程式碼區塊裡含有它的範例，都和真正的邊界無從分辨。這影響了所有四條會重新產生整合檔 UDS 區塊的寫入路徑：`uds update --integrations-only`、`uds update --apply` 的 `migrate_block` reconciler 路徑、`uds update --sync-refs`，以及 `uds check --restore`（XSPEC-418 R6 讓它也會還原受損的 UDS 區塊）。標記現在只在（去除前後空白後）獨占一整行、且那一行不在 fenced code block（``` ／ ~~~）內時才算數；所有呼叫點現在都經過同一個共用的 `locateMarkerBlock` 輔助函式，並以靜態掃描守衛測試強制執行，避免未來的呼叫點又退回直接用 `indexOf`／`includes`。含有兩組真正標記對的檔案（損壞，或手動編輯出錯）不再被猜測——每條寫入路徑都會拒絕執行並列出兩個標記所在行號，`uds check` 也會明確回報這個狀態，不再併入「已修改」或「找不到標記」。
+- **`uds check --ci` 可能畫面上印出整合區塊的 ✗，結尾卻仍宣稱專案符合標準並以結束碼 0 收尾。** `checkIntegrationBlocksIntegrity` 的檢查結果（區塊被修改／遺失／UDS 標記被移除）算出來也印出來了，卻在最終判定被丟棄——判定只看標準檔完整性。若你的 CI 一直對某個 CLAUDE.md／GEMINI.md 等檔案的 UDS 區塊實際上已被移除或改動的專案顯示綠燈，那就是這個缺陷；`--ci` 現在會正確地失敗，直到區塊被復原（`uds update --integrations-only`）或專案以其他方式恢復同步為止。互動式 `uds check`（不加 `--ci`）不受影響——仍以結束碼 0 收尾，不中斷一般使用。（XSPEC-418 R1）
+- **整合檔（CLAUDE.md、CLAUDE.local.md、AGENTS.md 等）同時被整份內容與 UDS 區塊兩套雜湊追蹤，兩套檢查在同一次執行裡可能互相矛盾。** 全新 `uds init` 從不替這些檔案記錄整份雜湊，但 `uds update --integrations-only` 會——跑過一次之後，使用者在 UDS 區塊**外**的任何修改（正是 marker-based update 承諾保留的自訂內容）都會讓 `uds check --ci` 報 `CLAUDE.md（已修改）` 並結束碼 1，而同一次輸出裡自己的區塊完整性檢查卻說區塊完好。另外，`uds check --restore` 正確地重寫了損壞的區塊（保留區塊外內容，沒有資料遺失），卻只更新了整份雜湊，從未更新區塊雜湊——於是下一次 check 對一個才剛被正確還原的區塊報 `CLAUDE.md（UDS 區塊已修改）`。整合檔現在不再寫進 `fileHashes`（只寫進本來就只追蹤區塊的 `integrationBlockHashes`）——走訪了所有寫入點，不只原始回報的兩處，包含 `--apply`／`--plan` 的 reconciler 路徑與 `--sync-refs`；既有 manifest 裡這類檔案殘留的整份雜湊，會在下一次 `uds update`（或 `uds check --restore`／`--migrate`）時被移除，區塊雜湊保留。`uds check --restore` 還原整合檔後，現在會把區塊雜湊更新成實際寫入的內容。已用一份真實採用者的 manifest（恰好帶有這個殘留欄位）驗證：同一份輸入，修正前 `uds check --ci` 結束碼 1，修正後結束碼 0。後續複核另發現兩個缺口，一併修掉：`uds check --restore` 過去對受損的 UDS 區塊完全無作用——它靠的是 `fileStatus`，而那完全由 `fileHashes` 建構，已不含整合檔，於是它悄悄還原了 0 個檔案而區塊仍是壞的；`--restore` 現在也會還原被判定為「已修改」或「標記遺失」的區塊（不動區塊外內容，`--restore-missing` 行為不變）。另外，因為上面新增的清除邏輯只掛在寫入路徑，既有 manifest 裡殘留的整份雜湊若不曾跑過寫入，純 `check` 永遠沒有機會清掉它——標準檔完整性檢查現在也會在讀取時略過同時被 `integrationBlockHashes` 追蹤的鍵，讓未跑過 `update` 的既有專案也能回報乾淨。（XSPEC-418 R6）
+
+### 新增
+
+- **`uds init --claude-target <project|local>` 與 `uds update --claude-target <project|local>`：在已有團隊 `CLAUDE.md` 的 repo 裡個人採用 UDS。** 過去 UDS 的 Claude Code 整合一律寫入 `CLAUDE.md`——團隊共用、會進版控的檔案——沒有任何改寫目標的方式。在已有團隊 `CLAUDE.md` 的 repo 裡個人採用 UDS 的使用者，只能手動把 UDS 區塊搬到 `CLAUDE.local.md`（Claude Code 原生支援、緊接在 `CLAUDE.md` 之後讀入的檔案），而從那一刻起 `check`／`update`／`uninstall` 全都回報錯誤，或悄悄寫回團隊檔案——包含在例行孤兒清理中把搬移後檔案自己的雜湊當「孤兒」刪掉。
+  `uds init` 的 `--claude-target local` 從一開始就把整合內容寫進 `CLAUDE.local.md`；團隊的 `CLAUDE.md` 完全不會被動到。`uds update --claude-target <project|local>` 則讓**既有**安裝不必重裝就能切換目標：從舊檔移除 UDS 區塊（保留寫在裡面的其他內容；若舊檔在移除後只剩 UDS 內容則整個刪除，與 `uninstall` 既有規則一致）、寫入新目標、並更新 manifest，不論新目標是否已存在手動搬過去的區塊。`check`、`update`（含 `--integrations-only`／`--force`）與孤兒雜湊清理現在都經同一個函式解出工具的實際目標檔，不再各自假設預設值——從未使用 `--claude-target` 的專案完全不受影響：manifest 只有在選擇 `local` 時才會多出 `integrationTargets` 欄位。`--claude-target` 不影響 `AGENTS.md`；若不想讓它進版控，一樣要自己透過 `.git/info/exclude` 排除。UDS 不會自動把 `CLAUDE.local.md` 寫進 `.gitignore`——請自行加入——且因為它未受版控，只存在於建立它的那個 git worktree。詳見 [CLI-INIT-OPTIONS.md](docs/CLI-INIT-OPTIONS.md)（「Claude Code 整合目標檔」一節）。（XSPEC-418 R2–R4）
+
 ## [6.10.0] - 2026-09-16
 
 ### 修正

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

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

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

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支援狀態 |
 |------|--------|
-| 6.10.0 | ✅ 最新正式版 |
+| 6.11.0 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已終止支援 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-TW/docs/CHEATSHEET.md

@@ -1,6 +1,6 @@
 # UDS 速查表
 
-> Quick reference for all UDS features | Last updated: 2026-09-14
+> Quick reference for all UDS features | Last updated: 2026-09-18
 
 **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
 

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-18
 
 **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
 
@@ -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`

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.11.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",