universal-dev-standards 6.2.7 → 6.3.1

package/bin/uds.js

@@ -15,6 +15,7 @@ import { skillsCommand } from '../src/commands/skills.js';
 import { agentListCommand, agentInstallCommand, agentInfoCommand } from '../src/commands/agent.js';
 import { aiContextInitCommand, aiContextValidateCommand, aiContextGraphCommand } from '../src/commands/ai-context.js';
 import { auditCommand } from '../src/commands/audit.js';
+import { depsCommand } from '../src/commands/deps.js';
 import { uninstallCommand } from '../src/commands/uninstall.js';
 import { specCreateCommand, specListCommand, specShowCommand, specConfirmCommand, specArchiveCommand, specDeleteCommand, specSearchCommand } from '../src/commands/spec.js';
 import { quickstartCommand } from '../src/commands/quickstart.js';
@@ -244,6 +245,14 @@ program
   .option('--threshold <n>', 'Score threshold for CI mode (default: 75)', '75')
   .action(auditCommand);
 
+program
+  .command('deps')
+  .description('Compare what you test against what your users install (published packages ship no lockfile)')
+  .option('--path <dir>', 'Directory containing package.json (default: cwd)')
+  .option('--json', 'Output raw JSON')
+  .option('--concurrency <n>', 'Parallel registry lookups (default: 8)')
+  .action(depsCommand);
+
 program
   .command('uninstall')
   .description('Remove UDS standards, integrations, skills, and hooks')

package/bundled/ai/standards/supply-chain-security-standards.ai.yaml

@@ -1,5 +1,13 @@
 id: supply-chain-security-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-04-01"
+  version: "1.1.0"
+  updated: "2026-08-04"
   source: core/supply-chain-security-standards.md
+  # NOTE: this file is a STUB. It carries no machine-readable rules, so an
+  # agent reading the ai/ layer gets nothing for this standard — the same is
+  # true of design-document-standards, estimation-standards and
+  # privacy-standards (4 of 141 as of 2026-08-04). The version above tracks
+  # the .md it points at; it does not mean the .md's rules are represented
+  # here. XSPEC-366 R4 rewrote that .md's Lock Strategy section and
+  # deliberately did not add a single rule here: one rule in an otherwise
+  # empty file would make coverage look better than it is.

package/bundled/core/supply-chain-security-standards.md

@@ -1,9 +1,9 @@
 # Supply Chain Security Standards
 
-> **Language**: English | [繁體中文](../locales/zh-TW/core/supply-chain-security-standards.md)
+> **Language**: English | [繁體中文](../locales/zh-TW/core/supply-chain-security-standards.md) | [简体中文](../locales/zh-CN/core/supply-chain-security-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-04-01
+**Version**: 1.1.0
+**Last Updated**: 2026-08-04
 **Applicability**: All software projects with external dependencies
 **Scope**: universal
 **Industry Standards**: SLSA, SPDX, CycloneDX, OpenSSF Scorecard
@@ -115,7 +115,7 @@ L1 (All projects) → L2 (CI/CD projects) → L3 (Security-critical) → L4 (Hig
 | **Patch** (x.y.Z) | Auto-merge after CI passes | Fully automated (Dependabot/Renovate) |
 | **Minor** (x.Y.0) | Auto-create PR, manual review | Semi-automated |
 | **Major** (X.0.0) | Manual evaluation, migration plan | Manual with changelog review |
-| **Lock Strategy** | Use lock files (package-lock.json, yarn.lock, Pipfile.lock) | Always committed to Git |
+| **Lock Strategy** | Commit lock files — **and, if you publish, separately verify what consumers resolve to** (see below) | Lock file committed; consumer resolution checked at release |
 
 ### Update Rules
 
@@ -124,6 +124,50 @@ L1 (All projects) → L2 (CI/CD projects) → L3 (Security-critical) → L4 (Hig
 - Security patches MUST be applied within 48 hours (Critical) or 7 days (High)
 - Major version upgrades SHOULD be evaluated quarterly
 
+### A lock file does not constrain your consumers
+
+A committed lock file makes **your** builds reproducible. It does not reach
+anyone who installs your package: a published npm tarball, a PyPI wheel, a
+Ruby gem — none of them carry the lock file. Consumers resolve your declared
+ranges themselves, at their install time, and get whatever satisfies them then.
+
+**When those two differ, your test suite is green about a combination nobody
+installs — and that green is indistinguishable from a real one.**
+
+This is the failure mode, observed rather than hypothesised: a project declared
+`"tree-sitter-c-sharp": "^0.23.1"`. Three published versions satisfied that
+range and they did not share an API. npm resolves a caret to the newest match,
+so every fresh install received the incompatible one, and **no C# file ever
+parsed for anyone who installed from the registry** — while the lock file
+pinned the working version and every test passed, for the entire life of that
+feature. The project's own source comments even documented the incompatible
+version; the caret quietly re-admitted it.
+
+Projects that **publish a package** therefore MUST additionally:
+
+- **Know what a consumer's install resolves to.** Compare, per runtime
+  dependency, the declared range, the locked version, and the version that
+  range resolves to today. Report only the differences — a table of agreeing
+  rows gets skimmed, and the ones that mattered go with it.
+- **Declare native dependencies as exact versions.** Packages with a native
+  binding (an install-family script, or a dependency on node-gyp / prebuild /
+  node-addon-api / cmake-js and equivalents) MUST NOT be declared with a range.
+  semver makes no promise about native ABI compatibility, and this has been
+  broken inside a minor range in practice. Flag these **whether or not they are
+  currently drifting**: a range matching exactly one published version is safe
+  because upstream has not published again, not because anything guarantees it.
+- **Run the test suite against consumer resolution before release.** Install
+  without the lock file and run the real suite against the result. This is the
+  only check in this section that does not need to be told in advance which
+  dependency will break.
+- **Treat a lookup that fails as unknown, never as agreement.** A check whose
+  "everything is fine" and "I could not find out" look the same converts an
+  unknown into a reassurance.
+
+> **Applies to published artifacts, not to applications.** A deployed service
+> ships its lock file with it, so its build and its runtime see the same
+> versions. This section is about packages other people install.
+
 ---
 
 ## CI/CD Integration

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

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.2.7
-translation_version: 6.2.7
-last_synced: 2026-07-31
+source_version: 6.3.1
+translation_version: 6.3.1
+last_synced: 2026-08-06
 status: current
 ---
 
@@ -17,6 +17,36 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.1] - 2026-08-06
+
+### 修复
+
+- **6.3.0 从来没有到达 npm——而这一版的存在，正是因为它自己描述的那个失效。** 发版流程有跑，它的 clean-room job 在 `npm ci` 这一步失败，错误是 `EUSAGE … Missing: @emnapi/core@1.11.3 from lock file`，`Publish to npm` 被跳过。lock 文件是被 `npm install --save semver` 重新生成的，过程中掉了 `npm ci` 需要的传递依赖项；我在本机跑的检查接受了它，所以这个不一致要到发版 job 才显形——那时 tag 与 GitHub Release 都已经公开。改以最后一份 `npm ci` 确实能通过的 lock 文件为基础重建，只加进 semver 那一笔，并在整个 CI 矩阵上验证，而不是只在一台机器上。
+- **`v6.3.0` 保留不删，其 release 说明已改为注明它从未发布。** 一个没有 npm 对应版本的 tag，正是 `uds deps` 被写出来要抓的那种不一致；删掉它移除的是证据，不是落差。**6.3.1 完整包含 6.3.0 的全部内容**，见下方。
+
+## [6.3.0] - 2026-08-04
+
+### 新增
+
+- **`uds deps`——你测的东西，跟你用户装的是同一个吗？** 发布出去的软件包不带 lockfile：你的 CI 測的是 `package-lock.json` 鎖定的版本，你的用户拿到的是声明范围在他们安装当下解析出的版本。两者不同时，整套测试会对着一个没有人会安装的组合亮绿灯，而那个绿灯与真绿灯无从分辨。此命令逐一比对每个 runtime 依赖的三个数字，**只报告差异**并附上分母——一份大多一致的表格会被略过，而其中真正有问题的那几行也跟着被略过。
+  - **原生依赖适用更严格的规则。** 带原生绑定的软件包只要以范围声明就会被标出，**不论它今天是否正在漂移**。semver 对原生 ABI 兼容性没有任何承诺，而这在本生态已被在 minor 范围内打破过。一个只对应到单一已发布版本的范围，安全是因为上游还没再发布，不是因为有任何保障——等漂移，等于等到用户已经拿到为止。
+  - **查询失败绝不记为一致。** 它会成为 `unverifiable` 并使整次检查失败。一个「没问题」与「我查不到」长得一样的检查，会把未知转成安心。
+  - `--path`、`--json`、`--concurrency`。
+
+### 变更
+
+- **`supply-chain-security-standards` 1.0.0 → 1.1.0——Lock Strategy 条目是对的，但不完整。** 它写「使用 lock 文件，一律进版本控制」，读起来是完整的，因此照着做的人没有任何理由再往下查——而一份提交的 lock 文件约束的是**你自己的**构建，碰不到你任何一个用户。回头改写正文而非加但书，因为在一条未变动的规则下方补「但请注意……」，会让原文那一行继续误导只读那一行的人，而标准表格多半就是一行一行读的。新章节以产生它的那个案例陈述失效、对会发布软件包的项目给出四项要求，并明确限定于发布出去的产物——部署的服务会连同 lock 文件一起发布，不受影响。
+
+### 备注
+
+- 该标准的 `.ai.yaml` 仍是五行的壳、没有任何机器可读规则——**141 份中的四份之一**，另含 `design-document-standards`、`estimation-standards` 与 `privacy-standards`，因此读 `ai/` 层的 agent 对这四份得到的都是空的。本次发版刻意没有把新增的那一条规则加进去：一条规则躺在一个原本全空的文件里，会让覆盖率看起来比实际好。该缺口现已记在文件内部。
+
+## [6.2.8] - 2026-07-31
+
+### 修复
+
+- **下载回来的标准，中文是坏的。** HTTPS 响应以 `data += chunk` 累积，而那会对每一个分块各自解码——于是任何字节跨在分块边界上的字符都变成替换字符（`日期` → `日�期`）。单字节的拉丁文不受影响；三字节的中日韩文字受影响。**过程中没有任何一步失败**：传输完成、文件写入、动作报告成功，损坏只有读文字才看得见。在一台机器上实测，**11 个项目的已安装标准里共约 278 个替换字符**。损害集中在 `requirement-checklist.md`、`requirement-template.md`、`requirement-document-template.md` 与 locale 包——也就是发布包不出货的那些文件（`files` 不含 `templates/` 与 `extensions/`），它们只可能靠下载取得。**若你的标准里有 `�`，请在 6.2.8 以上跑 `uds update --force`——重新下载的内容是正确的，会覆盖掉它们。**
+
 ## [6.2.7] - 2026-07-31
 
 ### 修复

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

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.2.7 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.1 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../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.2.7 | ✅ 最新正式版 |
+| 6.2.8 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-CN/core/supply-chain-security-standards.md

@@ -8,7 +8,7 @@ status: current
 
 # 供应链安全标准
 
-> 版本: 1.0.0 | 最后更新: 2026-04-01
+> 版本: 1.1.0 | 最后更新: 2026-08-04
 
 ## 概述
 
@@ -70,6 +70,40 @@ status: current
 | **Patch** (x.y.Z) | CI 通过后自动合并 | 全自动 |
 | **Minor** (x.Y.0) | 自动创建 PR，人工审查 | 半自动 |
 | **Major** (X.0.0) | 人工评估，迁移计划 | 手动 |
+| **锁定策略** | 提交 lock 文件——**若你发布软件包，另须验证消费端会解析到什么**（见下） | lock 文件进版本控制；发版时检查消费端解析 |
+
+### lock 文件约束不了你的用户
+
+提交 lock 文件让**你自己的**构建可重现。它到不了任何安装你软件包的人：发布出去的 npm
+tarball、PyPI wheel、Ruby gem 都不带 lock 文件。消费端是**在他们安装的当下、自行解析你
+声明的范围**，拿到当时满足该范围的任何版本。
+
+**两者不同时，你的测试套件会对着一个没有人会安装的组合亮绿灯——而那个绿灯与真绿灯
+无从分辨。**
+
+这是观察到的失效，不是假设的：某项目声明 `"tree-sitter-c-sharp": "^0.23.1"`，该区间有
+三个已发布版本而它们的 API 不同。npm 把 caret 解析到最新匹配版本，于是每一次全新安装
+都拿到不兼容的那个，**任何从 registry 安装的人的 C# 文件从未解析成功过**——而 lock 文件
+锁着能用的版本、每个测试都通过，横跨该功能的整个生命周期。该项目的源码注释甚至早就记录了
+那个不兼容版本；caret 悄悄把它又放了回来。
+
+因此**会发布软件包**的项目另须：
+
+- **知道消费端安装会解析到什么。** 逐一比对每个 runtime 依赖的声明范围、锁定版本，以及
+  该范围今天会解析到的版本。**只报告差异**——一份大多一致的表格会被略过，而其中真正
+  有问题的那几行也跟着被略过。
+- **原生依赖一律声明为精确版本。** 带原生绑定的软件包（有 install 家族脚本，或依赖
+  node-gyp／prebuild／node-addon-api／cmake-js 及同类者）**不得**以范围声明。semver 对
+  原生 ABI 兼容性没有任何承诺，而这在实践中已被在 minor 范围内打破过。**不论它今天是否
+  正在漂移都要标出**：一个只对应到单一已发布版本的范围，安全是因为上游还没再发布，
+  不是因为有任何保障。
+- **发版前以消费端解析跑一次测试套件。** 在没有 lock 文件的情况下安装，再对结果跑真正的
+  测试。这是本节唯一**不需要事先知道哪个依赖会坏**的检查。
+- **查不到的东西记为未知，绝不记为一致。** 一个「没问题」与「我查不到」长得一样的检查，
+  会把未知转成安心。
+
+> **适用于发布出去的产物，不适用于应用程序。** 一个部署出去的服务会连同 lock 文件一起
+> 发布，因此它的构建与运行看到的是同一组版本。本节谈的是**别人会安装的软件包**。
 
 ## 快速参考卡
 

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

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.2.7
-translation_version: 6.2.7
-last_synced: 2026-07-31
+source_version: 6.3.1
+translation_version: 6.3.1
+last_synced: 2026-08-06
 status: current
 ---
 
@@ -17,6 +17,36 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.1] - 2026-08-06
+
+### 修復
+
+- **6.3.0 從來沒有到達 npm——而這一版的存在，正是因為它自己描述的那個失效。** 發版流程有跑，它的 clean-room job 在 `npm ci` 這一步失敗，錯誤是 `EUSAGE … Missing: @emnapi/core@1.11.3 from lock file`，`Publish to npm` 被跳過。lock 檔是被 `npm install --save semver` 重新產生的，過程中掉了 `npm ci` 需要的傳遞相依項目；我在本機跑的檢查接受了它，所以這個不一致要到發版 job 才顯形——那時 tag 與 GitHub Release 都已經公開。改以最後一份 `npm ci` 確實能通過的 lock 檔為基礎重建，只加進 semver 那一筆，並在整個 CI 矩陣上驗證，而不是只在一台機器上。
+- **`v6.3.0` 保留不刪，其 release 說明已改為註明它從未發布。** 一個沒有 npm 對應版本的 tag，正是 `uds deps` 被寫出來要抓的那種不一致；刪掉它移除的是證據，不是落差。**6.3.1 完整包含 6.3.0 的全部內容**，見下方。
+
+## [6.3.0] - 2026-08-04
+
+### 新增
+
+- **`uds deps`——你測的東西，跟你使用者裝的是同一個嗎？** 發布出去的套件不帶 lockfile：你的 CI 測的是 `package-lock.json` 鎖定的版本，你的使用者拿到的是宣告範圍在他們安裝當下解析出的版本。兩者不同時，整套測試會對著一個沒有人會安裝的組合亮綠燈，而那個綠燈與真綠燈無從分辨。此指令逐一比對每個 runtime 相依的三個數字，**只回報差異**並附上分母——一份大多一致的表格會被略過，而其中真正有問題的那幾列也跟著被略過。
+  - **原生相依適用更嚴格的規則。** 帶原生綁定的套件只要以範圍宣告就會被標出，**不論它今天是否正在漂移**。semver 對原生 ABI 相容性沒有任何承諾，而這在本生態已被在 minor 範圍內打破過。一個只對應到單一已發布版本的範圍，安全是因為上游還沒再發布，不是因為有任何保障——等漂移，等於等到使用者已經拿到為止。
+  - **查詢失敗絕不記為一致。** 它會成為 `unverifiable` 並使整次檢查失敗。一個「沒問題」與「我查不到」長得一樣的檢查，會把未知轉成安心。
+  - `--path`、`--json`、`--concurrency`。
+
+### 變更
+
+- **`supply-chain-security-standards` 1.0.0 → 1.1.0——Lock Strategy 條目是對的，但不完整。** 它寫「使用 lock 檔，一律進版控」，讀起來是完整的，因此照著做的人沒有任何理由再往下查——而一份提交的 lock 檔約束的是**你自己的**建置，碰不到你任何一個使用者。回頭改寫本文而非加但書，因為在一條未變動的規則下方補「但請注意……」，會讓原文那一行繼續誤導只讀那一行的人，而標準表格多半就是一行一行讀的。新章節以產生它的那個案例陳述失效、對會發布套件的專案給出四項要求，並明確限定於發布出去的產物——部署的服務會連同 lock 檔一起出貨，不受影響。
+
+### 備註
+
+- 該標準的 `.ai.yaml` 仍是五行的殼、沒有任何機器可讀規則——**141 份中的四份之一**，另含 `design-document-standards`、`estimation-standards` 與 `privacy-standards`，因此讀 `ai/` 層的 agent 對這四份得到的都是空的。本次發版刻意沒有把新增的那一條規則加進去：一條規則躺在一個原本全空的檔案裡，會讓覆蓋率看起來比實際好。該缺口現已記在檔案內部。
+
+## [6.2.8] - 2026-07-31
+
+### 修復
+
+- **下載回來的標準，中文是壞的。** HTTPS 回應以 `data += chunk` 累積，而那會對每一個分塊各自解碼——於是任何位元組跨在分塊邊界上的字元都變成替換字元（`日期` → `日�期`）。單位元組的拉丁文不受影響；三位元組的中日韓文字受影響。**過程中沒有任何一步失敗**：傳輸完成、檔案寫入、動作回報成功，損壞只有讀文字才看得見。在一台機器上實測，**11 個專案的已安裝標準裡共約 278 個替換字元**。損害集中在 `requirement-checklist.md`、`requirement-template.md`、`requirement-document-template.md` 與 locale 包——也就是發布包不出貨的那些檔（`files` 不含 `templates/` 與 `extensions/`），它們只可能靠下載取得。**若你的標準裡有 `�`，請在 6.2.8 以上跑 `uds update --force`——重新下載的內容是正確的，會覆蓋掉它們。**
+
 ## [6.2.7] - 2026-07-31
 
 ### 修復

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

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.2.7 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.1 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../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.2.7 | ✅ 最新正式版 |
+| 6.2.8 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已終止支援 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->
 

package/bundled/locales/zh-TW/core/supply-chain-security-standards.md

@@ -8,7 +8,7 @@ status: current
 
 # 供應鏈安全標準
 
-> 版本: 1.0.0 | 最後更新: 2026-04-01
+> 版本: 1.1.0 | 最後更新: 2026-08-04
 
 ## 概述
 
@@ -70,6 +70,40 @@ status: current
 | **Patch** (x.y.Z) | CI 通過後自動合併 | 全自動 |
 | **Minor** (x.Y.0) | 自動建立 PR，人工審查 | 半自動 |
 | **Major** (X.0.0) | 人工評估，遷移計畫 | 手動 |
+| **鎖定策略** | 提交 lock 檔——**若你發布套件，另須驗證消費端會解析到什麼**（見下） | lock 檔進版控；發版時檢查消費端解析 |
+
+### lock 檔約束不了你的使用者
+
+提交 lock 檔讓**你自己的**建置可重現。它到不了任何安裝你套件的人：發布出去的 npm
+tarball、PyPI wheel、Ruby gem 都不帶 lock 檔。消費端是**在他們安裝的當下、自行解析你
+宣告的範圍**，拿到當時滿足該範圍的任何版本。
+
+**兩者不同時，你的測試套件會對著一個沒有人會安裝的組合亮綠燈——而那個綠燈與真綠燈
+無從分辨。**
+
+這是觀察到的失效，不是假設的：某專案宣告 `"tree-sitter-c-sharp": "^0.23.1"`，該區間有
+三個已發布版本而它們的 API 不同。npm 把 caret 解析到最新相符版本，於是每一次全新安裝
+都拿到不相容的那個，**任何從 registry 安裝的人的 C# 檔從未解析成功過**——而 lock 檔鎖著
+能用的版本、每個測試都通過，橫跨該功能的整個生命期。該專案的原始碼註解甚至早就記載了
+那個不相容版本；caret 悄悄把它又放了回來。
+
+因此**會發布套件**的專案另須：
+
+- **知道消費端安裝會解析到什麼。** 逐一比對每個 runtime 相依的宣告範圍、鎖定版本、以及
+  該範圍今天會解析到的版本。**只回報差異**——一份大多一致的表格會被略過，而其中真正
+  有問題的那幾列也跟著被略過。
+- **原生相依一律宣告為精確版本。** 帶原生綁定的套件（有 install 家族腳本，或相依
+  node-gyp／prebuild／node-addon-api／cmake-js 及同類者）**不得**以範圍宣告。semver 對
+  原生 ABI 相容性沒有任何承諾，而這在實務上已被在 minor 範圍內打破過。**不論它今天是否
+  正在漂移都要標出**：一個只對應到單一已發布版本的範圍，安全是因為上游還沒再發布，
+  不是因為有任何保障。
+- **發版前以消費端解析跑一次測試套件。** 在沒有 lock 檔的情況下安裝，再對結果跑真正的
+  測試。這是本節唯一**不需要事先知道哪個相依會壞**的檢查。
+- **查不到的東西記為未知，絕不記為一致。** 一個「沒問題」與「我查不到」長得一樣的檢查，
+  會把未知轉成安心。
+
+> **適用於發布出去的產物，不適用於應用程式。** 一個部署出去的服務會連同 lock 檔一起
+> 出貨，因此它的建置與執行看到的是同一組版本。本節談的是**別人會安裝的套件**。
 
 ## 快速參考卡
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.2.7",
+  "version": "6.3.1",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -63,7 +63,8 @@
     "chalk": "^5.3.0",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "ora": "^9.4.0"
+    "ora": "^9.4.0",
+    "semver": "^7.8.5"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/commands/deps.js

@@ -0,0 +1,112 @@
+/**
+ * `uds deps` — does what you test match what your users install?
+ * // implements XSPEC-366 R1
+ *
+ * A published npm package does not carry its lockfile. This compares, per
+ * runtime dependency, the declared range, the version the lockfile pins, and
+ * the version a consumer's install would actually resolve to.
+ *
+ * See `utils/dependency-resolution.js` for why resolution goes through
+ * `npm view` and why a failed lookup is never reported as agreement.
+ *
+ * @module commands/deps
+ */
+
+import chalk from 'chalk';
+import { measureResolutionDrift } from '../utils/dependency-resolution.js';
+
+/**
+ * Render the human-readable report.
+ *
+ * **Only the delta is listed.** A table of every dependency, mostly agreeing,
+ * is skimmed and then ignored — and the two rows that mattered go with it. The
+ * denominator is still printed, because "no drift" and "nothing was checked"
+ * produce the same silence otherwise, and only one of them is good news.
+ */
+function render(result) {
+  const lines = [];
+  const label = result.packageName ? chalk.bold(result.packageName) : result.root;
+
+  lines.push('');
+  lines.push(`${label} — ${result.examined} runtime dependenc${result.examined === 1 ? 'y' : 'ies'} checked`);
+
+  if (!result.hasLockfile) {
+    lines.push(chalk.yellow('  no package-lock.json — nothing to compare the registry against'));
+  }
+
+  if (result.drifted.length > 0) {
+    lines.push('');
+    lines.push(chalk.yellow(`  ${result.drifted.length} shipped ≠ tested:`));
+    for (const d of result.drifted) {
+      lines.push(
+        `    ${chalk.bold(d.name)}  ${chalk.dim(d.range)}` +
+          `  tested=${chalk.cyan(d.locked)}  users get=${chalk.yellow(d.resolved)}`
+      );
+    }
+    lines.push('');
+    lines.push(chalk.dim('  Your lockfile pins the tested column; consumers resolve the range'));
+    lines.push(chalk.dim('  themselves, because a published package does not ship a lockfile.'));
+  }
+
+  if (result.unpinnedNative.length > 0) {
+    lines.push('');
+    lines.push(chalk.yellow(`  ${result.unpinnedNative.length} native dependenc${result.unpinnedNative.length === 1 ? 'y is' : 'ies are'} behind a version range:`));
+    for (const n of result.unpinnedNative) {
+      lines.push(
+        `    ${chalk.bold(n.name)}  ${chalk.dim(n.range)}` +
+          `  ${chalk.dim('(' + n.native.reasons.join('; ') + ')')}`
+      );
+    }
+    lines.push('');
+    lines.push(chalk.dim('  Flagged whether or not they are drifting today. semver makes no'));
+    lines.push(chalk.dim('  promise about native ABI compatibility, and this ecosystem has'));
+    lines.push(chalk.dim('  broken it inside a minor range. A range that matches one published'));
+    lines.push(chalk.dim('  version is safe because upstream has not published again — waiting'));
+    lines.push(chalk.dim('  for drift means waiting until your users already have it.'));
+  }
+
+  if (result.unverifiable.length > 0) {
+    lines.push('');
+    lines.push(chalk.red(`  ${result.unverifiable.length} could not be checked:`));
+    for (const u of result.unverifiable) {
+      const why = u.error ?? 'not present in package-lock.json';
+      lines.push(`    ${chalk.bold(u.name)}  ${chalk.dim(u.range)}  ${chalk.red(why)}`);
+    }
+    lines.push('');
+    lines.push(chalk.dim('  These are unknowns, not agreements. Treating them as fine would'));
+    lines.push(chalk.dim('  turn "I could not find out" into "everything is fine".'));
+  }
+
+  if (result.clean) {
+    lines.push(chalk.green('  ✓ every dependency resolves to the version you test against'));
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function depsCommand(options = {}) {
+  const root = options.path ?? process.cwd();
+
+  let result;
+  try {
+    result = await measureResolutionDrift(root, {
+      concurrency: options.concurrency ? Number(options.concurrency) : undefined,
+    });
+  } catch (err) {
+    console.error(chalk.red(`uds deps: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(render(result));
+  }
+
+  // Drift and unverifiable both fail. Drift is a real divergence; unverifiable
+  // is an unknown, and a check that exits 0 on "I don't know" is a check that
+  // reports success for the case it was built to catch.
+  if (!result.clean) process.exitCode = 1;
+}

package/src/utils/dependency-resolution.js

@@ -0,0 +1,248 @@
+/**
+ * Shipped dependency resolution integrity. // implements XSPEC-366 R1
+ *
+ * **The problem this measures.** A published npm package does not carry its
+ * lockfile. Your CI tests the versions `package-lock.json` pins; your users get
+ * whatever the declared ranges resolve to at their install time. When those two
+ * differ, the entire test suite is green about a combination nobody installs —
+ * and that green is indistinguishable from a real one.
+ *
+ * This is not hypothetical. `engramgraph` declared
+ * `"tree-sitter-c-sharp": "^0.23.1"`. Three published versions satisfy that
+ * range and they do not share an API: 0.23.1 exports `nodeTypeInfo`, 0.23.5
+ * does not. npm resolves a caret to the newest match, so every fresh install
+ * received the incompatible one and **no C# file ever parsed for anyone who
+ * installed from npm** — while the lockfile pinned the working version and
+ * every test passed. See XSPEC-365 / XSPEC-366.
+ *
+ * ## Three design choices worth knowing
+ *
+ * **Only `dependencies` and `optionalDependencies` are examined.**
+ * `devDependencies` are not installed by consumers, so a drift there cannot
+ * reach them.
+ *
+ * **Resolution goes through `npm view`, not a hand-rolled registry fetch.**
+ * The question being asked is "what would resolve *in this environment*", and
+ * `npm view` honours the local npm configuration — private registries, scoped
+ * registries, auth, proxies. A direct fetch of registry.npmjs.org would
+ * silently answer a different question for anyone who does not install from
+ * the public registry, and would answer it confidently.
+ *
+ * **A registry lookup that fails is never folded into "consistent".** It
+ * becomes `unverifiable` and makes the whole check non-zero. A tool whose
+ * "everything is fine" and "I could not find out" look the same is worse than
+ * no tool: it converts an unknown into a reassurance.
+ *
+ * ## Native dependencies are held to a stricter rule (XSPEC-366 R2)
+ *
+ * A package with a native binding is flagged when its declared version is a
+ * range rather than an exact version — **even when it is not currently
+ * drifting**. That is not general dependency hygiene, it is a response to
+ * measured behaviour: the tree-sitter ecosystem has broken ABI inside a minor
+ * range, and semver makes no promise about native ABI compatibility.
+ *
+ * The distinction matters because "not drifting" is a fact about today. Four
+ * tree-sitter ranges in one AsiaOstrich project currently match exactly one
+ * published version each, so nothing drifts — while the range that caused the
+ * incident next door matched two. They are safe because upstream has not
+ * published again, not because anything guarantees it, and waiting for drift
+ * means waiting until users already have it.
+ */
+
+import { spawn } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import semver from 'semver';
+
+/** How many registry lookups to run at once. */
+const DEFAULT_CONCURRENCY = 8;
+
+/**
+ * Run `npm view <name>@<range> version --json` and return the highest version
+ * that satisfies the range.
+ *
+ * npm prints a bare JSON string when exactly one version matches and a JSON
+ * array when several do. The array is in publish order, **not** semver order —
+ * a backport released after a major bump appears last while being the lowest
+ * version — so the maximum is computed with semver rather than by taking the
+ * final element. Guessing here would produce a confident wrong answer, which
+ * is the failure mode this whole module exists to detect.
+ */
+async function resolveViaNpm(name, range, run) {
+  const { code, stdout, stderr } = await run(['view', `${name}@${range}`, 'version', '--json']);
+
+  if (code !== 0) {
+    const detail = (stderr || stdout || '').split('\n').find((l) => l.trim()) ?? '';
+    throw new Error(detail.trim() || `npm view exited ${code}`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error(`npm view returned output that is not JSON: ${stdout.slice(0, 120)}`);
+  }
+
+  if (typeof parsed === 'string') return parsed;
+  if (Array.isArray(parsed) && parsed.length > 0) {
+    const max = semver.maxSatisfying(parsed, range);
+    if (max) return max;
+    throw new Error(`no version in [${parsed.join(', ')}] satisfies ${range}`);
+  }
+  throw new Error('npm view returned no version');
+}
+
+/**
+ * Signals that a package carries a native binding, in the package's own
+ * manifest. Both are needed: `better-sqlite3@12.8.0` declares an `install`
+ * script *and* gyp-family dependencies, but its own 13.x dropped the install
+ * script while remaining native — a detector using only that signal would
+ * silently stop flagging it.
+ */
+const INSTALL_SCRIPTS = ['preinstall', 'install', 'postinstall'];
+const NATIVE_BUILD_DEPS = /node-gyp|prebuild|node-addon-api|cmake-js|^bindings$/;
+
+/** A declared version with no range operator at all. */
+function isExactVersion(range) {
+  return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(range.trim());
+}
+
+/**
+ * Fetch the manifest of one exact version and decide whether it is native.
+ *
+ * **The version is always specified.** `npm view <name> scripts` answers about
+ * the *latest* published version, not the one being examined — measured on
+ * 2026-08-04: `better-sqlite3` at latest reports no install script while the
+ * 12.8.0 actually in use declares one. Querying the bare name would produce a
+ * confident answer about a different package version, which is the exact class
+ * of error this whole module exists to detect.
+ *
+ * The full manifest is requested rather than named fields, because npm
+ * unwraps the object when only one requested field exists — asking for
+ * `scripts dependencies` on a package with no dependencies returns the scripts
+ * map itself, with no `scripts` key to read it from.
+ */
+async function classifyNative(name, version, run) {
+  const { code, stdout, stderr } = await run(['view', `${name}@${version}`, '--json']);
+  if (code !== 0) {
+    const detail = (stderr || stdout || '').split('\n').find((l) => l.trim()) ?? '';
+    throw new Error(detail.trim() || `npm view exited ${code}`);
+  }
+  const manifest = JSON.parse(stdout);
+  const scripts = manifest.scripts ?? {};
+  const deps = { ...(manifest.dependencies ?? {}) };
+
+  const reasons = [];
+  const hookNames = INSTALL_SCRIPTS.filter((k) => typeof scripts[k] === 'string');
+  if (hookNames.length > 0) reasons.push(`${hookNames.join('/')} script`);
+  const buildDeps = Object.keys(deps).filter((d) => NATIVE_BUILD_DEPS.test(d));
+  if (buildDeps.length > 0) reasons.push(`depends on ${buildDeps.join(', ')}`);
+
+  return { native: reasons.length > 0, reasons };
+}
+
+/** Default runner: spawn npm and collect its output. */
+function spawnNpm(cwd) {
+  return (args) =>
+    new Promise((resolve) => {
+      const child = spawn('npm', args, { cwd, shell: process.platform === 'win32' });
+      let stdout = '';
+      let stderr = '';
+      child.stdout.on('data', (d) => (stdout += d));
+      child.stderr.on('data', (d) => (stderr += d));
+      child.on('error', (err) => resolve({ code: -1, stdout: '', stderr: err.message }));
+      child.on('close', (code) => resolve({ code, stdout, stderr }));
+    });
+}
+
+/** Map over `items` with a bounded number of concurrent workers. */
+async function mapWithConcurrency(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (;;) {
+      const index = next++;
+      if (index >= items.length) return;
+      results[index] = await worker(items[index], index);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
+/**
+ * Compare, for every runtime dependency of the package at `root`: the declared
+ * range, the version the lockfile pins, and the version a consumer's install
+ * would resolve to.
+ *
+ * @param {string} root Directory containing package.json.
+ * @param {object} [options]
+ * @param {number} [options.concurrency]
+ * @param {(args: string[]) => Promise<{code: number, stdout: string, stderr: string}>} [options.run]
+ *   Injected for tests, so the unit tests do not depend on the network — the
+ *   thing being tested is the comparison and the failure handling, not npm.
+ * @returns {Promise<object>} measurement result; see the shape below.
+ */
+export async function measureResolutionDrift(root, options = {}) {
+  const pkgPath = join(root, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(`no package.json at ${root}`);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+
+  const lockPath = join(root, 'package-lock.json');
+  const lock = existsSync(lockPath) ? JSON.parse(readFileSync(lockPath, 'utf8')) : null;
+
+  const declared = [
+    ...Object.entries(pkg.dependencies ?? {}).map(([name, range]) => ({ name, range, kind: 'dependencies' })),
+    ...Object.entries(pkg.optionalDependencies ?? {}).map(([name, range]) => ({ name, range, kind: 'optionalDependencies' })),
+  ];
+
+  const run = options.run ?? spawnNpm(root);
+  const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+
+  const rows = await mapWithConcurrency(declared, concurrency, async (dep) => {
+    const locked = lock?.packages?.[`node_modules/${dep.name}`]?.version ?? null;
+    let resolved;
+    try {
+      resolved = await resolveViaNpm(dep.name, dep.range, run);
+    } catch (err) {
+      return { ...dep, locked, resolved: null, native: null, error: err.message };
+    }
+    try {
+      const native = await classifyNative(dep.name, resolved, run);
+      return { ...dep, locked, resolved, native, error: null };
+    } catch (err) {
+      // The version resolved but the manifest did not. We cannot say whether
+      // this one needs pinning, and saying nothing would read as "it doesn't".
+      return { ...dep, locked, resolved, native: null, error: `could not classify: ${err.message}` };
+    }
+  });
+
+  // A dependency with no lockfile entry is not "consistent" — it is unknown.
+  // Reporting it as fine because there was nothing to compare against would be
+  // the same class of mistake as reporting a failed lookup as fine.
+  const unverifiable = rows.filter((r) => r.error !== null || r.locked === null);
+  const drifted = rows.filter((r) => r.error === null && r.locked !== null && r.locked !== r.resolved);
+
+  // XSPEC-366 R2. Independent of drift on purpose: a native dependency behind
+  // a range is exposed whether or not upstream has published into it yet.
+  const unpinnedNative = rows.filter(
+    (r) => r.native?.native === true && !isExactVersion(r.range)
+  );
+
+  const consistent = rows.length - unverifiable.length - drifted.length;
+
+  return {
+    root,
+    packageName: pkg.name ?? null,
+    hasLockfile: lock !== null,
+    examined: rows.length,
+    consistent,
+    drifted,
+    unverifiable,
+    unpinnedNative,
+    /** True when every dependency was checked, agreed, and needs no pinning. */
+    clean: drifted.length === 0 && unverifiable.length === 0 && unpinnedNative.length === 0,
+  };
+}

package/src/utils/github.js

@@ -90,13 +90,32 @@ function httpGet(url) {
         return;
       }
 
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => resolve({
-        data,
-        statusCode: res.statusCode,
-        headers: res.headers
-      }));
+      // Collect Buffers and decode once at the end. `data += chunk` decoded each
+      // chunk on its own, so any character whose bytes straddled a chunk boundary
+      // became U+FFFD on both sides of the split. Latin text survived because its
+      // characters are one byte; Chinese standards are three bytes each and did
+      // not. `uds update --force` on one project downloaded four files and wrote
+      // 30 replacement characters into them — `日期` → `日�期`, `結構` → `結�構`
+      // — and reported every action as succeeded, because as far as the CLI was
+      // concerned the transfer completed and the file was written. (XSPEC-343)
+      const chunks = [];
+      res.on('data', chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+      res.on('end', () => {
+        // try/catch because a throw inside an event handler does not reject the
+        // enclosing promise — it escapes, and the caller's await hangs forever.
+        // The first draft of this fix passed strings to Buffer.concat and the
+        // test run simply stopped, with no error to read. A hang is a worse
+        // failure than an exception: there is nothing to grep for.
+        try {
+          resolve({
+            data: Buffer.concat(chunks).toString('utf8'),
+            statusCode: res.statusCode,
+            headers: res.headers
+          });
+        } catch (err) {
+          reject(err);
+        }
+      });
       res.on('error', reject);
     }).on('error', reject);
   });

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.2.7",
+  "version": "6.3.1",
   "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.2.7"
+      "version": "6.3.1"
     },
     "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.2.7",
+      "version": "6.3.1",
       "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.2.7",
+      "version": "6.3.1",
       "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.2.7",
+      "version": "6.3.1",
       "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.2.7",
+      "version": "6.3.1",
       "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.2.7",
+      "version": "6.3.1",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"