universal-dev-standards 6.4.0 → 6.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/bundled/ai/standards/agent-dispatch.ai.yaml +162 -0
  2. package/bundled/ai/standards/ai-friendly-architecture.ai.yaml +1 -1
  3. package/bundled/ai/standards/ai-instruction-standards.ai.yaml +190 -15
  4. package/bundled/ai/standards/ai-response-navigation.ai.yaml +43 -3
  5. package/bundled/ai/standards/class-level-fix.ai.yaml +38 -3
  6. package/bundled/ai/standards/commit-message.ai.yaml +2 -0
  7. package/bundled/ai/standards/model-selection.ai.yaml +370 -72
  8. package/bundled/ai/standards/mutation-testing.ai.yaml +105 -2
  9. package/bundled/ai/standards/project-structure.ai.yaml +1 -1
  10. package/bundled/ai/standards/security-standards.ai.yaml +22 -1
  11. package/bundled/ai/standards/spec-driven-development.ai.yaml +86 -2
  12. package/bundled/ai/standards/test-governance.ai.yaml +49 -2
  13. package/bundled/ai/standards/testing.ai.yaml +49 -3
  14. package/bundled/ai/standards/translation-lifecycle-standards.ai.yaml +4 -4
  15. package/bundled/ai/standards/verification-evidence.ai.yaml +48 -4
  16. package/bundled/core/ai-response-navigation.md +75 -2
  17. package/bundled/core/class-level-fix.md +26 -3
  18. package/bundled/core/model-selection.md +383 -125
  19. package/bundled/core/mutation-testing.md +41 -2
  20. package/bundled/core/spec-driven-development.md +57 -2
  21. package/bundled/core/test-governance.md +22 -2
  22. package/bundled/core/translation-lifecycle-standards.md +6 -6
  23. package/bundled/core/verification-evidence.md +42 -3
  24. package/bundled/locales/zh-CN/CHANGELOG.md +24 -3
  25. package/bundled/locales/zh-CN/README.md +1 -1
  26. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  27. package/bundled/locales/zh-CN/core/ai-response-navigation.md +69 -5
  28. package/bundled/locales/zh-CN/core/model-selection.md +375 -60
  29. package/bundled/locales/zh-CN/core/mutation-testing.md +1 -1
  30. package/bundled/locales/zh-CN/core/spec-driven-development.md +1 -1
  31. package/bundled/locales/zh-CN/core/test-governance.md +1 -1
  32. package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +1 -1
  33. package/bundled/locales/zh-CN/core/verification-evidence.md +1 -1
  34. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +7 -12
  35. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +10 -15
  36. package/bundled/locales/zh-TW/CHANGELOG.md +49 -3
  37. package/bundled/locales/zh-TW/README.md +1 -1
  38. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  39. package/bundled/locales/zh-TW/core/ai-response-navigation.md +69 -5
  40. package/bundled/locales/zh-TW/core/class-level-fix.md +22 -7
  41. package/bundled/locales/zh-TW/core/model-selection.md +385 -47
  42. package/bundled/locales/zh-TW/core/mutation-testing.md +45 -6
  43. package/bundled/locales/zh-TW/core/spec-driven-development.md +1 -1
  44. package/bundled/locales/zh-TW/core/test-governance.md +22 -3
  45. package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +1 -1
  46. package/bundled/locales/zh-TW/core/verification-evidence.md +33 -6
  47. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +7 -12
  48. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +10 -15
  49. package/bundled/locales/zh-TW/integrations/claude-code/README.md +31 -5
  50. package/package.json +1 -1
  51. package/src/utils/reference-sync.js +83 -16
  52. package/standards-registry.json +20 -8
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../core/verification-evidence.md
3
- source_version: 1.2.0
4
- translation_version: 1.2.0
5
- last_synced: 2026-07-17
3
+ source_version: 1.3.0
4
+ translation_version: 1.3.0
5
+ last_synced: 2026-08-14
6
6
  status: current
7
7
  ---
8
8
 
@@ -10,8 +10,8 @@ status: current
10
10
 
11
11
  > **語言**: [English](../../../core/verification-evidence.md) | 繁體中文
12
12
 
13
- **版本**: 1.2.0
14
- **最後更新**: 2026-07-17
13
+ **版本**: 1.3.0
14
+ **最後更新**: 2026-08-14
15
15
  **適用性**: 所有 AI 輔助開發工作流
16
16
  **範圍**: 通用 (Universal)
17
17
  **靈感來源**: [Superpowers](https://github.com/obra/superpowers) — verification-before-completion (MIT)
@@ -40,6 +40,7 @@ status: current
40
40
  | 環境層次 (Environment Layer) | 該證據是從哪個環境蒐集而來(`local` / `uat` / `prd`) |
41
41
  | 證據有效性 (Evidence Validity) | 證據*本身*是否可信 —— 亦即驗證指令究竟有沒有真的執行、有沒有真的量到它宣稱量到的東西 |
42
42
  | 工具靜默失敗 (Silent Tool Failure) | 驗證指令根本沒跑起來,或跑了但什麼都沒量到,卻產生了與真實結果無從分辨的輸出 |
43
+ | 證據新鮮度 (Evidence Freshness) | 證據是否由**最後一次編輯受測程式碼、提示詞或設定之後**才執行的一次執行所產生 —— 而不是沿用一次針對更早狀態的執行結果 |
43
44
 
44
45
  ---
45
46
 
@@ -169,7 +170,7 @@ status: current
169
170
 
170
171
  這不是幻覺。幻覺是虛構你沒查過的事。這是反過來:**你查了,而那個查詢工具騙了你。** `anti-hallucination` 標準涵蓋不到這一塊 —— 該標準的每一條禁令都是某種形式的「不要編造」,而這裡沒有任何東西被編造。
171
172
 
172
- ### 四條有效性規則
173
+ ### 五條有效性規則
173
174
 
174
175
  **1. 只有在「成功時回傳 0」的工具上,`exit_code = 0` 才代表成功。**
175
176
 
@@ -187,6 +188,16 @@ status: current
187
188
 
188
189
  在 `set -o pipefail` 下,`producer | grep -q pattern` 會繼承 `producer` 的非零值,與 `grep` 有沒有匹配到無關。當決策取決於內容時,**先捕捉輸出,再評估它** —— 不要讓一個 pipeline 把兩個問題壓縮成一個數字。
189
190
 
191
+ **5. 證據必須晚於它所驗證對象的最後一次編輯。**
192
+
193
+ 在受測程式碼、提示詞或設定的**最近一次變更之前**擷取的驗證執行,證明的是別的東西 —— 不是正在被主張的那件事。這個陷阱是靜默的:完整套件先跑過且全綠,之後才編輯了某個東西(提示詞、設定檔、門檻),而編輯之後只跑了範圍更窄的檢查(lint、部分套件)—— 結果卻拿更早的那次綠燈當作現狀的證據。**證據必須是最後一次編輯之後的單一次新鮮執行,不是「剛好通過的最近一次執行」。**
194
+
195
+ ### 過期證據 —— 一種失效樣態
196
+
197
+ 規則 1–4 假設證據**在正確的地方**被蒐集且被正確解讀。它們沒有回答「**什麼時候**」這個問題。一個執行了、量測正確、也回傳真結果的指令,依然可能撐不起一個完成聲明 —— 如果它跑完之後有東西又變了。
198
+
199
+ **失效樣態**:完整測試套件跑過且通過。之後,某個提示詞或設定值被編輯 —— 沒有任何測試直接涵蓋那次編輯。提交前只跑了 `lint`,也通過。commit 引用「測試通過」作為證據。接著 CI 紅在一個釘住剛剛被改掉那份內容的測試上 —— 那個「通過」的套件,跑的是一個在主張被提出時已經不存在的版本。
200
+
190
201
  ### 此失效模式的實例證據
191
202
 
192
203
  以下是某 AI 代理於 2026-07-17 實際執行的驗證指令,每一道都導出了自信而錯誤的結論,並被當成事實回報出去:
@@ -216,11 +227,24 @@ status: current
216
227
  | 有 `verification_evidence` 但 `exit_code ≠ 0` | 標記為**驗證失敗** —— **除非**已知該工具在受測狀態下本就會以非零退出(證據有效性規則 1),此時改以輸出判定 |
217
228
  | `exit_code = 0`,但該指令不可能量到它所宣稱的事 | 標記為**未驗證** —— 一道在錯的地方執行、或根本沒執行的通過指令,不是證據 |
218
229
  | 證據主張「不存在」(`0`、空輸出、「查無」) | 在證明查詢工具成功執行過之前,標記為**未驗證** |
230
+ | 證據的時間戳早於它所驗證對象的最後一次編輯 | 標記為**過期(stale)** —— 須在編輯後重跑,不得引用更早那次通過 |
219
231
  | 多個驗證步驟 | **全部**步驟都必須通過 |
220
232
  | 代理提供的是錯誤指令的證據 | 標記為**未驗證** |
221
233
 
222
234
  ---
223
235
 
236
+ ## 窄涵蓋必須登記,不能只揭露
237
+
238
+ Evidence Validity 與 Environment Stratification Matrix 都允許一個被記錄下來的缺口 —— 一個無法驗證某個維度的環境層次、一項量測範圍窄於它所支撐主張的檢查。單純寫下這個缺口本身並不夠:散文比真正補上缺口便宜,而一個從未被重新檢視的揭露,會悄悄變成「這份證據其實撐不起它被用來支撐的主張」的永久藉口。
239
+
240
+ **要求**:任何這一類已記錄的缺口,必須同時登記到一份**帶到期日的例外清冊** —— 獨立於標準本文或 matrix 條目本身之外 —— 指名缺口、其成因、並附上覆核或到期日期。只有一則註腳而沒有對應清冊條目,不滿足本條。
241
+
242
+ **可證偽條件**:一則清冊條目連續兩期審查都未變動,代表該揭露已經變成逃生口,本條對該條目失效 —— 不是「部分滿足」,是失效。清冊放在哪裡、什麼格式、多久審一次,留給採用專案自行決定;本標準只要求「有這麼一份東西存在,且條目會動」。
243
+
244
+ 這與[類別層修正標準](class-level-fix.md)的窄涵蓋規則是同一條要求,套用在驗證證據而非類別層檢查上:兩種情況下,一個永遠不必改變的揭露都不是揭露,是一份穿著揭露外衣的永久豁免。
245
+
246
+ ---
247
+
224
248
  ## 規則
225
249
 
226
250
  | ID | 觸發條件 | 動作 | 優先級 |
@@ -235,6 +259,8 @@ status: current
235
259
  | VE-008 | 證據主張「不存在」(`0`、空輸出、「查無」) | 在證明查詢工具成功執行過之前一律無效。以不壓抑 stderr 的方式重跑 | High |
236
260
  | VE-009 | 存在性/不存在性檢查壓抑了 stderr(`2>/dev/null` 或等價寫法) | 證據不成立。以 stderr 可見的方式重跑 | High |
237
261
  | VE-010 | 證據的 `exit_code` 來自 pipeline(尤其是在 `pipefail` 下) | 該 code 不歸屬於任何單一階段。改為捕捉輸出並評估內容 | Medium |
262
+ | VE-011 | 證據的執行時間戳早於它所宣稱驗證之產物的最後一次編輯 | 標記為**過期(stale)** —— 對現狀不成立為證據;要求在編輯後補一次單一次新鮮執行 | High |
263
+ | VE-012 | 文件化的證據/涵蓋缺口(environment-stratification ⚠️/❌,或任何窄於其主張的檢查)沒有登記到帶到期日的例外清冊 | 揭露本身不滿足此規則 —— 要求一則已登記、帶到期日的清冊條目,指名缺口與其覆核/到期日期 | Required |
238
264
 
239
265
  ---
240
266
 
@@ -314,6 +340,7 @@ verification_evidence:
314
340
  - [測試標準](testing-standards.md) —— 產生多數證據的那些測試是怎麼寫的
315
341
  - [代理派遣與並行協調](agent-dispatch.md) —— 委派出去的工作會回傳主張,那些主張需要套用本標準
316
342
  - [部署標準](deployment-standards.md) —— 定義 VE-005 / VE-006 所引用的「環境分層責任矩陣」
343
+ - [類別層修正標準](class-level-fix.md) —— 與 VE-012 相同的「窄涵蓋必須登記」要求,套用在類別層檢查而非驗證證據上
317
344
 
318
345
  ---
319
346
 
@@ -1,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-08-10
3
+ > Quick reference for all UDS features | Last updated: 2026-08-12
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
6
6
 
@@ -240,7 +240,7 @@
240
240
  | `logging-standards` | Logging Standards |
241
241
  | `mock-boundary` | This document defines rules for what can and canno |
242
242
  | `model-provenance` | Model Provenance Policy Standards |
243
- | `model-selection` | Define a cost-effective strategy for selecting AI |
243
+ | `model-selection` | Define how to choose **which model** and **how dee |
244
244
  | `multi-environment-e2e-testing` | Multi-Environment E2E Testing Standards |
245
245
  | `mutation-testing` | Mutation testing evaluates test suite effectivenes |
246
246
  | `no-cicd-deployment` | No-CI/CD Deployment Strategy |
@@ -319,27 +319,22 @@
319
319
  | `aggregate-effectiveness.mjs` | Aggregate Standards Effectiveness Reports |
320
320
  | `analyze-hook-stats.mjs` | Hook Statistics Analyzer (SPEC-SELFDIAG-001 REQ-7, |
321
321
  | `bump-version.mjs` | Build a platform-aware shell command for a .sh scr |
322
- | `bump-version.sh` | DEPRECATED: Use 'node scripts/bump-version.mjs <ve |
322
+ | `bump-version.sh` | Thin wrapper — scripts/bump-version.mjs is the onl |
323
323
  | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
324
324
  | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
325
- | `check-ai-behavior-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-ai-behavior |
326
325
  | `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse |
327
326
  | `check-cli-docs-sync.ps1` | Check Cli Docs Sync |
328
327
  | `check-cli-docs-sync.sh` | CLI-to-Documentation Sync Checker |
329
328
  | `check-commands-sync.ps1` | Check Commands Sync |
330
329
  | `check-commands-sync.sh` | Commands Sync Checker |
331
- | `check-commit-spec-reference.sh` | DEPRECATED: Use 'npx tsx scripts/check-commit-spec |
330
+ | `check-commit-spec-reference.sh` | Thin wrapper — scripts/check-commit-spec-reference |
332
331
  | `check-docs-integrity.ps1` | Check Docs Integrity |
333
332
  | `check-docs-integrity.sh` | Documentation Integrity Checker |
334
333
  | `check-docs-sync.ps1` | Check Docs Sync |
335
334
  | `check-docs-sync.sh` | Documentation Sync Checker |
336
335
  | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ- |
337
- | `check-flow-gate-report.sh` | DEPRECATED: Use 'npx tsx scripts/check-flow-gate-r |
338
- | `check-integration-commands-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-integration |
339
336
  | `check-orphan-specs.ps1` | Check Orphan Specs |
340
337
  | `check-orphan-specs.sh` | Orphan Spec Detection Script |
341
- | `check-registry-completeness.sh` | DEPRECATED: Use 'npx tsx scripts/check-registry-co |
342
- | `check-release-readiness-signoff.sh` | DEPRECATED: Use 'npx tsx scripts/check-release-rea |
343
338
  | `check-scope-sync.ps1` | Check Scope Sync |
344
339
  | `check-scope-sync.sh` | Scope Consistency Check Script |
345
340
  | `check-skill-next-steps-sync.ps1` | Check Skill Next Steps Sync |
@@ -356,16 +351,16 @@
356
351
  | `check-usage-docs-sync.sh` | check-usage-docs-sync.sh |
357
352
  | `check-version-sync.ps1` | Check Version Sync |
358
353
  | `check-version-sync.sh` | Version Sync Checker |
359
- | `check-workflow-compliance.sh` | DEPRECATED: Use 'npx tsx scripts/check-workflow-co |
354
+ | `check-workflow-compliance.sh` | Thin wrapper — scripts/check-workflow-compliance.t |
360
355
  | `commitlint-bilingual-rule.mjs` | commitlint-bilingual-rule.mjs — custom commitlint |
361
356
  | `convert-md-to-yaml.mjs` | Markdown to AI-YAML Conversion Script |
362
357
  | `fix-manifest-paths.ps1` | Fix Manifest Paths |
363
358
  | `fix-manifest-paths.sh` | Manifest Path Fixer |
364
- | `generate-docs.mjs` | Sync the "AI Tool Support" table's Skills/Slash Co |
359
+ | `generate-docs.mjs` | Look up the release date for `version` from CHANGE |
365
360
  | `generate-locale-coverage.mjs` | Locale Coverage Generator |
366
361
  | `generate-version-manifest.mjs` | Generate Version Manifest (SPEC-SELFDIAG-001 REQ-9 |
367
362
  | `install-hooks.mjs` | Install Hooks |
368
- | `install-hooks.sh` | DEPRECATED: Use 'node scripts/install-hooks.mjs' i |
363
+ | `install-hooks.sh` | Thin wrapper — scripts/install-hooks.mjs is the on |
369
364
  | `pre-commit.mjs` | Build a platform-aware shell command for a .sh scr |
370
365
  | `pre-release-check.ps1` | Pre Release Check |
371
366
  | `pre-release-check.sh` | Pre-release Check Script |
@@ -1,7 +1,7 @@
1
1
  # UDS 功能參考手冊
2
2
 
3
3
  > Universal Development Standards - 完整功能文件
4
- > Auto-generated | Last updated: 2026-08-10
4
+ > Auto-generated | Last updated: 2026-08-12
5
5
 
6
6
  **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
7
7
 
@@ -15,9 +15,9 @@
15
15
  4. [代理](#agents) (5)
16
16
  5. [工作流程](#workflows) (5)
17
17
  6. [核心規範](#core-standards) (150)
18
- 7. [腳本](#scripts) (59)
18
+ 7. [腳本](#scripts) (54)
19
19
 
20
- **Total Features: 334**
20
+ **Total Features: 329**
21
21
 
22
22
  ---
23
23
 
@@ -367,7 +367,7 @@
367
367
  | `logging-standards` | 1.4.0 | |
368
368
  | `mock-boundary` | 1.1.0 | This document defines rules for what can and cannot be mocked in tests. Its goal |
369
369
  | `model-provenance` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
370
- | `model-selection` | 1.0.1 | Define a cost-effective strategy for selecting AI model tiers based on task comp |
370
+ | `model-selection` | 2.1.0 | Define how to choose **which model** and **how deeply it should think** — two in |
371
371
  | `multi-environment-e2e-testing` | 1.0.0 | **Status**: Active | **Updated**: 2026-05-13 | |
372
372
  | `mutation-testing` | 1.0.0 | Mutation testing evaluates test suite effectiveness by injecting artificial bugs |
373
373
  | `no-cicd-deployment` | - | |
@@ -428,7 +428,7 @@
428
428
  | `testing-standards` | 3.2.0 | This standard defines actionable testing rules and conventions for AI agents and |
429
429
  | `timeout-standards` | - | |
430
430
  | `token-budget` | - | |
431
- | `translation-lifecycle-standards` | 1.0.0 | Translation lifecycle standards: MISSING vs OUTDATED distinction, semver-aware s |
431
+ | `translation-lifecycle-standards` | 1.0.1 | Translation lifecycle standards: MISSING vs OUTDATED distinction, semver-aware s |
432
432
  | `user-journey-testing` | - | |
433
433
  | `user-story-mapping` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
434
434
  | `verification-evidence` | 1.2.0 | Establish an "Iron Law" that no task can be claimed as complete without verifica |
@@ -448,27 +448,22 @@
448
448
  | `aggregate-effectiveness.mjs` | Aggregate Standards Effectiveness Reports |
449
449
  | `analyze-hook-stats.mjs` | Hook Statistics Analyzer (SPEC-SELFDIAG-001 REQ-7, AC-11) |
450
450
  | `bump-version.mjs` | Build a platform-aware shell command for a .sh script. |
451
- | `bump-version.sh` | DEPRECATED: Use 'node scripts/bump-version.mjs <version>' instead (cross-platform). |
451
+ | `bump-version.sh` | Thin wrapper — scripts/bump-version.mjs is the only copy of the bump logic. |
452
452
  | `check-ai-agent-sync.ps1` | Check Ai Agent Sync |
453
453
  | `check-ai-agent-sync.sh` | AI Agent Sync Checker |
454
- | `check-ai-behavior-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-ai-behavior-sync.ts' instead (cross-platform). |
455
454
  | `check-ai-yaml-parses.mjs` | Every shipped .ai.yaml must parse, and must parse into what it says. |
456
455
  | `check-cli-docs-sync.ps1` | Check Cli Docs Sync |
457
456
  | `check-cli-docs-sync.sh` | CLI-to-Documentation Sync Checker |
458
457
  | `check-commands-sync.ps1` | Check Commands Sync |
459
458
  | `check-commands-sync.sh` | Commands Sync Checker |
460
- | `check-commit-spec-reference.sh` | DEPRECATED: Use 'npx tsx scripts/check-commit-spec-reference.ts' instead (cross-platform). |
459
+ | `check-commit-spec-reference.sh` | Thin wrapper — scripts/check-commit-spec-reference.ts is the only copy of |
461
460
  | `check-docs-integrity.ps1` | Check Docs Integrity |
462
461
  | `check-docs-integrity.sh` | Documentation Integrity Checker |
463
462
  | `check-docs-sync.ps1` | Check Docs Sync |
464
463
  | `check-docs-sync.sh` | Documentation Sync Checker |
465
464
  | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ-5, AC-7) |
466
- | `check-flow-gate-report.sh` | DEPRECATED: Use 'npx tsx scripts/check-flow-gate-report.ts' instead (cross-platform). |
467
- | `check-integration-commands-sync.sh` | DEPRECATED: Use 'npx tsx scripts/check-integration-commands-sync.ts' instead (cross-platform). |
468
465
  | `check-orphan-specs.ps1` | Check Orphan Specs |
469
466
  | `check-orphan-specs.sh` | Orphan Spec Detection Script |
470
- | `check-registry-completeness.sh` | DEPRECATED: Use 'npx tsx scripts/check-registry-completeness.ts' instead (cross-platform). |
471
- | `check-release-readiness-signoff.sh` | DEPRECATED: Use 'npx tsx scripts/check-release-readiness-signoff.ts' instead (cross-platform). |
472
467
  | `check-scope-sync.ps1` | Check Scope Sync |
473
468
  | `check-scope-sync.sh` | Scope Consistency Check Script |
474
469
  | `check-skill-next-steps-sync.ps1` | Check Skill Next Steps Sync |
@@ -485,16 +480,16 @@
485
480
  | `check-usage-docs-sync.sh` | check-usage-docs-sync.sh |
486
481
  | `check-version-sync.ps1` | Check Version Sync |
487
482
  | `check-version-sync.sh` | Version Sync Checker |
488
- | `check-workflow-compliance.sh` | DEPRECATED: Use 'npx tsx scripts/check-workflow-compliance.ts' instead (cross-platform). |
483
+ | `check-workflow-compliance.sh` | Thin wrapper — scripts/check-workflow-compliance.ts is the only copy of the |
489
484
  | `commitlint-bilingual-rule.mjs` | commitlint-bilingual-rule.mjs — custom commitlint rules enforcing the |
490
485
  | `convert-md-to-yaml.mjs` | Markdown to AI-YAML Conversion Script |
491
486
  | `fix-manifest-paths.ps1` | Fix Manifest Paths |
492
487
  | `fix-manifest-paths.sh` | Manifest Path Fixer |
493
- | `generate-docs.mjs` | Sync the "AI Tool Support" table's Skills/Slash Commands numeric columns |
488
+ | `generate-docs.mjs` | Look up the release date for `version` from CHANGELOG.md's own |
494
489
  | `generate-locale-coverage.mjs` | Locale Coverage Generator |
495
490
  | `generate-version-manifest.mjs` | Generate Version Manifest (SPEC-SELFDIAG-001 REQ-9, AC-14) |
496
491
  | `install-hooks.mjs` | Install Hooks |
497
- | `install-hooks.sh` | DEPRECATED: Use 'node scripts/install-hooks.mjs' instead (cross-platform). |
492
+ | `install-hooks.sh` | Thin wrapper — scripts/install-hooks.mjs is the only copy of the installer |
498
493
  | `pre-commit.mjs` | Build a platform-aware shell command for a .sh script. |
499
494
  | `pre-release-check.ps1` | Pre Release Check |
500
495
  | `pre-release-check.sh` | Pre-release Check Script |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../../integrations/claude-code/README.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
5
- last_synced: 2026-04-22
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ last_synced: 2026-08-12
6
6
  status: current
7
7
  ---
8
8
 
@@ -10,8 +10,8 @@ status: current
10
10
 
11
11
  > **語言**: English | [繁體中文](README.md)
12
12
 
13
- **版本**: 1.0.0
14
- **最後更新**: 2026-01-29
13
+ **版本**: 1.1.0
14
+ **最後更新**: 2026-08-12
15
15
 
16
16
  本目錄包含將通用開發標準 (Universal Development Standards) 與 [Claude Code](https://docs.anthropic.com/claude-code) 整合的資源。
17
17
 
@@ -21,6 +21,32 @@ Claude Code 是一個先進的 AI 編碼代理,可以直接與您的程式碼
21
21
 
22
22
  1. **專案上下文 (`CLAUDE.md`)**:定義專案特定的規則、風格指南和指令。
23
23
  2. **技能 (`skills/`)**:針對 TDD、SDD、程式碼審查等的專業能力。
24
+ 3. **模型層級 × effort 映射**:`core/model-selection.md` 的宿主層那一半。
25
+ 4. **參考 subagent 定義**:`.claude/agents/*.md`,每個模型層級各一份。
26
+ 5. **跨 repo 派工模板**:當目標 repo 不是你的 session 所在的那一個時,subagent 的 prompt 必須自帶什麼。
27
+
28
+ ## 本宿主的模型選擇(XSPEC-362 R5)
29
+
30
+ `core/model-selection.md` 依規則保持 vendor-neutral——它把 tier(`fast` / `standard` / `capable`)
31
+ 與 effort 級距(`low` … `max`)定義為標籤,並明白表示它無法斷言某個模型接受哪些 effort 級距。
32
+ 下列檔案為 Claude Code 回答這件事,且是本 repo **唯一**應該出現具體模型識別字的地方。
33
+
34
+ | 檔案 | 內容 |
35
+ |---|---|
36
+ | [`model-selection-mapping.md`](../../../../integrations/claude-code/model-selection-mapping.md) | tier → `model`、effort → `effort`、已解析的 tier × effort 表格,以及硬邊界登記表 |
37
+ | [`model-selection-mapping.ai.yaml`](../../../../integrations/claude-code/model-selection-mapping.ai.yaml) | 同一份映射的機器可讀版 |
38
+ | [`.claude/agents/`](../../../../integrations/claude-code/.claude/agents/) | 四份參考 subagent 定義:三層各一,外加一個長時程變體 |
39
+ | [`dispatch-template.md`](../../../../integrations/claude-code/dispatch-template.md) | 跨 repo 派工模板,以及支撐它的實測 |
40
+
41
+ 該映射有兩件事值得先知道:
42
+
43
+ - **UDS 的 `very-high` 在 Claude Code 寫作 `xhigh`。** 這是唯一名稱不同的一級。標準不改名去遷就工具,
44
+ 改名由宿主層吸收。
45
+ - **`fast` 層在本宿主沒有 effort 軸。** 該層的模型不接受任何 effort 級距,
46
+ 所以標準的「先調 effort 再升級模型層」在那裡沒有東西可調。
47
+
48
+ 派工機制——並行安全、獨立域、狀態協定——**不**由這些檔案涵蓋。
49
+ 那屬於 [`core/agent-dispatch.md`](../../../../core/agent-dispatch.md),這些檔案引用它而不重寫它。
24
50
 
25
51
  ## 設定
26
52
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "universal-dev-standards",
3
- "version": "6.4.0",
3
+ "version": "6.6.0",
4
4
  "description": "CLI tool for adopting Universal Development Standards",
5
5
  "keywords": [
6
6
  "documentation",
@@ -75,18 +75,35 @@ export const STANDARD_TO_CATEGORY = {
75
75
  * Matches patterns like:
76
76
  * - Reference: .standards/anti-hallucination.md
77
77
  * - 參考: .standards/anti-hallucination.md (Chinese)
78
+ * - Reference: .standards/a.ai.yaml, .standards/options/b.ai.yaml (more than one)
79
+ * - Reference: `.standards/a.ai.yaml` (quoted, as markdown renders it)
80
+ *
81
+ * The first version anchored `.standards/` directly after the label and ran to
82
+ * the first space, which made it see EXACTLY ONE path per line, keep whatever
83
+ * punctuation followed it, and miss any path that was quoted. Measured on the
84
+ * two telemetry repos: of three references it reported, one was a false
85
+ * positive (`commit-message.ai.yaml,` — the file exists, the comma did not),
86
+ * and it silently skipped two more, one of which
87
+ * (`workflow-enforcement.ai.yaml`) does not exist in any repo or upstream.
78
88
  *
79
89
  * @param {string} content - Integration file content
80
90
  * @returns {string[]} - Array of referenced standard filenames (e.g., ['anti-hallucination.md'])
81
91
  */
82
92
  export function parseReferences(content) {
83
- // Match both English and Chinese reference patterns
84
- const referencePattern = /(?:Reference|參考):\s*\.standards\/([^\s\n)]+)/gi;
93
+ // Both English and Chinese labels, and both colon widths.
94
+ const referenceLinePattern = /(?:Reference|參考)[::][^\n]*/gi;
95
+ // Every `.standards/` path on that line, stopping at anything that quotes or
96
+ // separates rather than names: whitespace, brackets, backticks, quotes,
97
+ // commas and semicolons.
98
+ const pathPattern = /\.standards\/([^\s\n)\]`,;'"]+)/g;
85
99
  const references = new Set();
86
- let match;
87
100
 
88
- while ((match = referencePattern.exec(content)) !== null) {
89
- references.add(match[1]);
101
+ for (const line of content.match(referenceLinePattern) ?? []) {
102
+ for (const [, path] of line.matchAll(pathPattern)) {
103
+ // Sentence punctuation is not part of a filename.
104
+ const cleaned = path.replace(/[.,;:!?]+$/, '');
105
+ if (cleaned) references.add(cleaned);
106
+ }
90
107
  }
91
108
 
92
109
  return Array.from(references);
@@ -113,6 +130,42 @@ export function getStandardCategory(sourcePath) {
113
130
  return STANDARD_TO_CATEGORY[fileName] || null;
114
131
  }
115
132
 
133
+ /**
134
+ * Reduce a standard to the identity all three of its spellings share.
135
+ *
136
+ * The same standard appears as a manifest stem (`commit-message`), a shipped
137
+ * file (`commit-message.ai.yaml`) and a human-readable reference
138
+ * (`.standards/commit-message.md`). Comparing any two of those literally
139
+ * fails, and it fails as "this standard is not adopted".
140
+ *
141
+ * @param {string} pathOrName - Any of the three spellings
142
+ * @returns {string} - Bare stem, e.g. 'commit-message'
143
+ */
144
+ export function standardStem(pathOrName) {
145
+ return pathOrName
146
+ .split('/')
147
+ .pop()
148
+ .replace(/\.(ai\.yaml|yaml|md)$/i, '');
149
+ }
150
+
151
+ /**
152
+ * Category for a standard, accepting a manifest stem as well as a filename.
153
+ *
154
+ * {@link STANDARD_TO_CATEGORY} is keyed by filename; manifests store stems.
155
+ * Looking a stem up directly always missed, which is what emptied
156
+ * `manifestCategories`.
157
+ *
158
+ * @param {string} pathOrName - Manifest stem, filename or reference path
159
+ * @returns {string|null} - Category ID, or null when the table does not cover it
160
+ */
161
+ function categoryForStandard(pathOrName) {
162
+ const fileName = pathOrName.split('/').pop();
163
+ if (STANDARD_TO_CATEGORY[fileName]) return STANDARD_TO_CATEGORY[fileName];
164
+
165
+ const stem = standardStem(pathOrName);
166
+ return STANDARD_TO_CATEGORY[`${stem}.md`] || STANDARD_TO_CATEGORY[`${stem}.ai.yaml`] || null;
167
+ }
168
+
116
169
  /**
117
170
  * Compare manifest standards with integration file references
118
171
  *
@@ -124,27 +177,44 @@ export function getStandardCategory(sourcePath) {
124
177
  * - syncedRefs: Standards that are properly synced
125
178
  */
126
179
  export function compareStandardsWithReferences(manifestStandards, integrationReferences) {
127
- // Compare at category level to handle .md vs .ai.yaml format differences
128
- // e.g., manifest has 'anti-hallucination.ai.yaml' but integration references 'anti-hallucination.md'
180
+ // The manifest is the source of truth for what this project adopted, so ask
181
+ // it directly. The category map below is a hand-written table covering a
182
+ // small fraction of the standards UDS ships (compare its size against
183
+ // `cli/standards-registry.json` — a count written here would go stale the
184
+ // next time a standard lands); using it as the primary test reported every
185
+ // standard outside the table as "not in manifest", which is a different
186
+ // claim, and a false one.
187
+ //
188
+ // It was worse than partial coverage: manifest entries are bare stems
189
+ // (`commit-message`) while the table is keyed by filename
190
+ // (`commit-message.md`), so `manifestCategories` came out EMPTY on the
191
+ // current manifest format and every reference fell through to orphaned.
192
+ // Both halves were wrong at once, which is why the output still looked
193
+ // plausible — three orphans reported on the telemetry repos, one of which
194
+ // (`commit-message.ai.yaml`) is adopted, and the only genuinely dead one
195
+ // (`workflow-enforcement.ai.yaml`) was not among them.
196
+ const manifestStems = new Set(manifestStandards.map(standardStem));
197
+
129
198
  const manifestCategories = new Set();
130
199
  for (const std of manifestStandards) {
131
- const fileName = std.split('/').pop();
132
- const category = STANDARD_TO_CATEGORY[fileName];
200
+ const category = categoryForStandard(std);
133
201
  if (category) {
134
202
  manifestCategories.add(category);
135
203
  }
136
204
  }
137
205
 
138
- // References in integration file but not backed by any manifest standard (by category)
206
+ // A reference is orphaned when nothing in the manifest answers to it, by
207
+ // stem (extension- and directory-insensitive) or by legacy category name.
139
208
  const orphanedRefs = integrationReferences.filter(ref => {
140
- const category = STANDARD_TO_CATEGORY[ref];
209
+ if (manifestStems.has(standardStem(ref))) return false;
210
+ const category = categoryForStandard(ref);
141
211
  return !category || !manifestCategories.has(category);
142
212
  });
143
213
 
144
214
  // Categories in manifest but not referenced in integration file
145
215
  const refCategories = new Set();
146
216
  for (const ref of integrationReferences) {
147
- const category = STANDARD_TO_CATEGORY[ref];
217
+ const category = categoryForStandard(ref);
148
218
  if (category) {
149
219
  refCategories.add(category);
150
220
  }
@@ -157,10 +227,7 @@ export function compareStandardsWithReferences(manifestStandards, integrationRef
157
227
  });
158
228
 
159
229
  // Properly synced references
160
- const syncedRefs = integrationReferences.filter(ref => {
161
- const category = STANDARD_TO_CATEGORY[ref];
162
- return category && manifestCategories.has(category);
163
- });
230
+ const syncedRefs = integrationReferences.filter(ref => !orphanedRefs.includes(ref));
164
231
 
165
232
  return { orphanedRefs, missingRefs, syncedRefs };
166
233
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "version": "6.4.0",
3
+ "version": "6.6.0",
4
4
  "lastUpdated": "2026-05-13",
5
5
  "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
6
6
  "formats": {
@@ -58,14 +58,14 @@
58
58
  "standards": {
59
59
  "name": "universal-dev-standards",
60
60
  "url": "https://github.com/AsiaOstrich/universal-dev-standards",
61
- "version": "6.4.0"
61
+ "version": "6.6.0"
62
62
  },
63
63
  "skills": {
64
64
  "name": "universal-dev-standards",
65
65
  "url": "https://github.com/AsiaOstrich/universal-dev-standards",
66
66
  "localPath": "skills",
67
67
  "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
68
- "version": "6.4.0",
68
+ "version": "6.6.0",
69
69
  "note": "Skills are now included in the main repository under skills/"
70
70
  }
71
71
  },
@@ -1728,7 +1728,19 @@
1728
1728
  },
1729
1729
  "category": "skill",
1730
1730
  "skillName": null,
1731
- "description": "Three-tier model selection strategy (fast/standard/capable) with cost-effective escalation"
1731
+ "description": "Two-axis model selection: model tier (reasoning ceiling × specification definiteness) × effort (reasoning depth), plus reverse-exclusion hard boundaries and four-state capability routing"
1732
+ },
1733
+ {
1734
+ "id": "agent-dispatch",
1735
+ "name": "Agent Dispatch & Parallel Coordination",
1736
+ "nameZh": "代理派遣與並行協調",
1737
+ "source": {
1738
+ "human": "core/agent-dispatch.md",
1739
+ "ai": "ai/standards/agent-dispatch.ai.yaml"
1740
+ },
1741
+ "category": "skill",
1742
+ "skillName": null,
1743
+ "description": "Parallel sub-agent dispatch: independent-domain criterion (no shared mutable state), four-state status protocol, conflict detection, prompt design principles"
1732
1744
  },
1733
1745
  {
1734
1746
  "id": "git-worktree",
@@ -2248,7 +2260,7 @@
2248
2260
  "id": "license-compliance",
2249
2261
  "name": "License Compliance Standards",
2250
2262
  "nameZh": "授權合規標準",
2251
- "version": "6.4.0",
2263
+ "version": "6.6.0",
2252
2264
  "source": {
2253
2265
  "human": "core/license-compliance.md",
2254
2266
  "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2260,7 +2272,7 @@
2260
2272
  "id": "verification-oracle",
2261
2273
  "name": "Verification Oracle Standards",
2262
2274
  "nameZh": "驗證 Oracle 標準",
2263
- "version": "6.4.0",
2275
+ "version": "6.6.0",
2264
2276
  "source": {
2265
2277
  "human": "core/verification-oracle.md",
2266
2278
  "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2272,7 +2284,7 @@
2272
2284
  "id": "model-provenance",
2273
2285
  "name": "Model Provenance Policy Standards",
2274
2286
  "nameZh": "模型來源政策標準",
2275
- "version": "6.4.0",
2287
+ "version": "6.6.0",
2276
2288
  "source": {
2277
2289
  "human": "core/model-provenance.md",
2278
2290
  "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2284,7 +2296,7 @@
2284
2296
  "id": "resource-cost-boundary",
2285
2297
  "name": "Resource / Cost Boundary Declaration Standards",
2286
2298
  "nameZh": "資源/成本邊界宣告標準",
2287
- "version": "6.4.0",
2299
+ "version": "6.6.0",
2288
2300
  "source": {
2289
2301
  "human": "core/resource-cost-boundary.md",
2290
2302
  "ai": "ai/standards/resource-cost-boundary.ai.yaml"