universal-dev-standards 6.14.0-beta.6 → 6.14.0-beta.8

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 (99) hide show
  1. package/README.md +13 -3
  2. package/bin/uds.js +30 -6
  3. package/bundled/ai/options/code-review/pr-review.ai.yaml +20 -1
  4. package/bundled/ai/standards/code-review.ai.yaml +15 -2
  5. package/bundled/ai/standards/developer-memory.ai.yaml +12 -2
  6. package/bundled/ai/standards/full-coverage-testing.ai.yaml +44 -6
  7. package/bundled/ai/standards/open-work-tracking.ai.yaml +191 -11
  8. package/bundled/ai/standards/pipeline-security-gates.ai.yaml +48 -3
  9. package/bundled/ai/standards/project-context-memory.ai.yaml +12 -2
  10. package/bundled/core/code-review-checklist.md +20 -2
  11. package/bundled/core/developer-memory.md +12 -2
  12. package/bundled/core/full-coverage-testing.md +44 -4
  13. package/bundled/core/open-work-tracking.md +156 -16
  14. package/bundled/core/pipeline-security-gates.md +63 -0
  15. package/bundled/core/project-context-memory.md +10 -2
  16. package/bundled/locales/zh-CN/CHANGELOG.md +78 -3
  17. package/bundled/locales/zh-CN/README.md +1 -1
  18. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  19. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +13 -4
  20. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  21. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +7 -1
  22. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +13 -3
  23. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +7 -1
  24. package/bundled/locales/zh-CN/core/code-review-checklist.md +17 -0
  25. package/bundled/locales/zh-CN/core/developer-memory.md +9 -0
  26. package/bundled/locales/zh-CN/core/full-coverage-testing.md +48 -8
  27. package/bundled/locales/zh-CN/core/pipeline-security-gates.md +64 -4
  28. package/bundled/locales/zh-CN/core/project-context-memory.md +5 -0
  29. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +70 -0
  30. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +4 -3
  31. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +25 -23
  32. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +13 -11
  33. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +6 -6
  34. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +7 -1
  35. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +44 -0
  36. package/bundled/locales/zh-CN/options/code-review/pr-review.md +13 -2
  37. package/bundled/locales/zh-TW/CHANGELOG.md +78 -3
  38. package/bundled/locales/zh-TW/README.md +1 -1
  39. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  40. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +13 -4
  41. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  42. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +7 -1
  43. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +13 -3
  44. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -1
  45. package/bundled/locales/zh-TW/core/code-review-checklist.md +17 -0
  46. package/bundled/locales/zh-TW/core/developer-memory.md +9 -0
  47. package/bundled/locales/zh-TW/core/full-coverage-testing.md +48 -8
  48. package/bundled/locales/zh-TW/core/open-work-tracking.md +90 -14
  49. package/bundled/locales/zh-TW/core/pipeline-security-gates.md +64 -4
  50. package/bundled/locales/zh-TW/core/project-context-memory.md +5 -0
  51. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +70 -0
  52. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +4 -3
  53. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +25 -23
  54. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +13 -11
  55. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +6 -6
  56. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +7 -1
  57. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +44 -0
  58. package/bundled/locales/zh-TW/options/code-review/pr-review.md +13 -2
  59. package/bundled/skills/SKILL_NAMING.md +9 -0
  60. package/bundled/templates/gates/check-anti-fake-tests.mjs +305 -5
  61. package/package.json +3 -1
  62. package/src/commands/audit.js +9 -2
  63. package/src/commands/check.js +17 -0
  64. package/src/commands/hitl.js +3 -0
  65. package/src/commands/init.js +41 -21
  66. package/src/commands/list.js +12 -3
  67. package/src/commands/mcp.js +2 -3
  68. package/src/commands/open-work.js +65 -6
  69. package/src/commands/quickstart.js +29 -13
  70. package/src/commands/release.js +41 -17
  71. package/src/commands/skills.js +19 -33
  72. package/src/commands/spec-split.js +28 -16
  73. package/src/commands/spec.js +34 -13
  74. package/src/commands/uninstall.js +2 -2
  75. package/src/commands/update.js +61 -61
  76. package/src/core/open-work-config.js +103 -0
  77. package/src/flows/init-flow.js +10 -0
  78. package/src/hitl/manager.js +4 -2
  79. package/src/i18n/messages.js +240 -63
  80. package/src/installers/skills-installer.js +3 -1
  81. package/src/mcp/__tests__/server.test.js +0 -1
  82. package/src/mcp/server.js +16 -4
  83. package/src/prompts/init.js +148 -13
  84. package/src/reconciler/index.js +42 -5
  85. package/src/uninstallers/skills-uninstaller.js +83 -16
  86. package/src/uninstallers/standards-uninstaller.js +56 -7
  87. package/src/utils/agents-installer.js +10 -17
  88. package/src/utils/available-standards-report.js +144 -0
  89. package/src/utils/available-standards.js +216 -0
  90. package/src/utils/copier.js +5 -4
  91. package/src/utils/friction-detector.js +27 -0
  92. package/src/utils/open-work-tracking.mjs +919 -48
  93. package/src/utils/prompt-closed.js +18 -0
  94. package/src/utils/skill-frontmatter.js +102 -0
  95. package/src/utils/skill-name-collision.js +169 -0
  96. package/src/utils/skills-install-paths.js +114 -0
  97. package/src/utils/skills-installer.js +63 -105
  98. package/src/utils/transient-fs.js +113 -0
  99. package/standards-registry.json +34 -9
@@ -4,11 +4,11 @@
4
4
  standard:
5
5
  id: open-work-tracking
6
6
  name: Open Work Tracking Standard
7
- description: 開放工作追蹤標準——承載開放工作的地方必須低摩擦收件、記錄解除條件、生成可推導欄位、印出分母、在回合結束時被檢視而不阻斷、把目標與進度分開並替目標的修改留痕、且讓每個下一步點名具體對象
7
+ description: 開放工作追蹤標準——承載開放工作的地方必須低摩擦收件、記錄解除條件、生成可推導欄位、印出分母、在回合結束時被檢視而不阻斷、把目標與進度分開並替目標的修改留痕、讓每個下一步點名具體對象、分得出「還沒問」與「已問、等回覆」、讓看不見的事實有一個帶戳記、可誠實寫成「未知」、年齡看得見的存放處,並讓等待可以用邏輯名稱點名另一個專案裡的東西、說清楚這台機器看不看得到它
8
8
 
9
9
  meta:
10
- version: "1.1.0"
11
- updated: "2026-09-30"
10
+ version: "1.4.0"
11
+ updated: "2026-10-07"
12
12
  source: core/open-work-tracking.md
13
13
  description: >
14
14
  三種不同的「工作不見了」的方式(沒地方記新想法、等待中沒有解除條件、
@@ -17,13 +17,26 @@ standard:
17
17
  本標準管「離開之後抵達的那個承載庫,自己會不會腐壞」。
18
18
  1.1.0 補兩個缺口:目標(意圖)與進度存放在不同載體、目標的修改要留痕(OWT-017/018);
19
19
  下一步要點名具體對象(OWT-019)。
20
+ 1.2.0 補兩個狀態:等待分成「還沒問」與「已問、等回覆」(OWT-020/021/022);
21
+ 助理看不到的外部事實容許一個窄例外——手寫列附觀察者、觀察時間,值可誠實寫成未知,
22
+ 年齡一律顯示(OWT-023/024/025/026)。
23
+ 1.3.0 補兩件事:等待可以用邏輯名稱點名另一個專案裡的東西,並分成已解除/尚未解除/從這裡看不到/需要人判斷四種回報,
24
+ 紀錄放在每個相關專案的 session 都讀得到、受版本控制的地方(OWT-027/028/029);
25
+ 「下一步」詞彙補上三個明確同義詞、採用者可宣告自己的詞(不新增要求編號,OWT-019 與 OWT-016 的具體作法)。
26
+ 1.4.0 不新增要求編號:處於 asked-awaiting 並滿足 OWT-022 的項目,其下一步可以就是等待的那個回覆,由 OWT-022 判定、不由 OWT-019 判定
27
+ (第四種結果 waiting-on-reply,單獨計數、顯示年齡、不算已點名也不算完成;next-action 與 waiting 以同一個函式讀同一列,不會給相反結論);
28
+ 並補一段說明:OWT-007 的摘要可由程式在回合結束時印出、完整版按需取得(不新增要求、不新增檢查)。
20
29
 
21
30
  iron_law: >
22
31
  一個承載開放工作的地方,必須:不要求分類就能收下新項目、為每一個等待中項目記下解除條件、
23
32
  對可推導的欄位改用生成、回報還剩什麼時同時揭露看不到什麼、
24
33
  在控制權從 agent 交回人的那一刻被檢視——而且那個檢視不能讓回合失敗;
25
34
  把「這份工作為了什麼」與「做到哪了」分開存放並替前者的每次修改留下交代;
26
- 讓每一個「下一步」都點名一個讀的人找得到的東西。
35
+ 讓每一個「下一步」都點名一個讀的人找得到的東西;
36
+ 分得出「還沒問」與「已問、等回覆」,並讓看不見的事實有一個帶戳記的存放處——
37
+ 未知是正式的值、永遠不算完成,每筆觀察的年齡一律顯示;
38
+ 讓一個等待可以用邏輯名稱點名另一個專案裡的東西、說明這台機器看不看得到它——看不到的單獨計數、
39
+ 既不算已解除也不算零——並把那份紀錄放在每個相關專案的 session 都讀得到、受版本控制的地方。
27
40
 
28
41
  # ── 寫法約束:先讀這一段,它拘束下面每一條 ────────────────────────────────
29
42
  # 與 deferred-item-exit 受的是同一條約束(DEC-049),套用在下游一層:
@@ -38,6 +51,9 @@ standard:
38
51
  - "一個回報數字與它看不到的部分之間的關係"
39
52
  - "控制權交回人的那一點存在一個確認點,且它永不阻斷"
40
53
  - "一次目標的修改與說明它的修訂紀錄之間必須存在的關係"
54
+ - "一個等待項目的狀態與「有沒有人問過」的紀錄之間必須存在的關係"
55
+ - "一筆手寫事實與它的戳記、值域、年齡之間必須存在的關係"
56
+ - "一個等待的解除條件與它所點名的另一個專案裡的物件之間必須存在的關係(邏輯名稱,不是目錄)"
41
57
  inadmissible_how:
42
58
  - "收件點是哪個 app、檔案或工單系統"
43
59
  - "輪詢解除條件的排程器或機器人"
@@ -45,6 +61,8 @@ standard:
45
61
  - "儀表板版面或報告範本"
46
62
  - "用什麼 hook 系統、shell 或 cron 實作確認點"
47
63
  - "哪一種版本控制系統、核可工具或檔案配置承載目標或其修訂紀錄"
64
+ - "訊息用哪個管道、哪個工具送出,或哪個系統記錄對方的回覆"
65
+ - "跨專案的紀錄存在哪一個 repo、哪一個工具的 session 之間怎麼傳訊(只規定它受版本控制、各方 session 讀得到)"
48
66
  consequence: >
49
67
  本標準不附帶任何閘門。它只說一個承載開放工作的地方必須具備什麼性質;
50
68
  有沒有東西在檢查是採用專案的決定,而 OWT-014/OWT-015 是用來讓那個決定
@@ -67,7 +85,17 @@ standard:
67
85
  - "目標/驗收條件/限制(意圖)與進度/下一步存在不同的載體;判準是結構(小節、欄位、型別化標記),不是檔名——更新進度不得需要碰目標"
68
86
  - "目標或驗收條件每次被修改都留下「改了什麼、誰核可、為什麼」;沒有核可者的修改要在控制權交回人時列出來,不得靜默,但列出只是回報、永不阻斷"
69
87
  - "「下一步」欄位至少點名一個具體對象——檔案路徑、測試名稱、指令或需求編號之一;只有動詞不算。這是結構判準,不判斷措辭好壞"
88
+ - "處於 asked-awaiting 並滿足 OWT-022(asked-at、在等什麼、解除事件齊全)的項目,其下一步可以就是等待的那個回覆:由 OWT-022 判定、不由 OWT-019 判定,回報為 waiting-on-reply——不算違反、不算已點名、不算完成,單獨列出並顯示年齡;缺任一項、not-yet-asked、其他狀態、寫成小節標題的下一步,照舊由 OWT-019 判定"
70
89
  - "點名對象的辨認本身是樣式比對,涵蓋率明示為未知;回報三態(點名且已找到/點名但未找到/未點名),只有未點名是違反"
90
+ - "標為等待的項目要說明自己是「還沒問」(請求已草擬或已決定、尚未送出)還是「已問、等回覆」(已送出、沒有回音);兩者皆非的等待項目要被個別點名,不得併入總數、不得算成已完成"
91
+ - "「還沒問」的項目點名那份草稿或那個動作(沿用 OWT-019 的辨認);「已問、等回覆」的項目帶 asked-at,並滿足 OWT-002"
92
+ - "手寫列只容許用在承載庫無法從版控、規格標記或 CI 結果推導的事實;每一列帶 observed-by、observed-at,值為 yes/no/unknown。檢查只判定欄位存在且格式正確,絕不判定觀察為真"
93
+ - "unknown 是正式的值:單獨計數、單獨顯示,永遠不算完成;標為完成而值是 unknown 即違反"
94
+ - "每筆觀察顯示年齡;超過宣告門檻者回報為「觀察已舊」、另計、不算已確認。戳只說誰何時看到,不說現在仍然如此"
95
+ - "手寫例外不及於版控、規格標記或 CI 結果已能決定的欄位(OWT-003 仍成立);這靠一份主題詞表判定,涵蓋率未知"
96
+ - "等待的解除條件可以點名另一個專案裡的物件,寫成 <專案>:<物件>;專案是邏輯名稱,載體裡不得有機器專屬的絕對路徑;名稱對應哪個目錄宣告在載體之外"
97
+ - "對每個跨專案解除條件回報四種之一,單獨計數:已解除、尚未解除、從這裡看不到(不是已解除也不是零)、需要人判斷;查找只讀本機檔案與版本控制,不連網"
98
+ - "等著另一個專案的工作,其紀錄放在受版本控制、每個相關專案的 session 都讀得到的 repo;不得只放在個人的 AI 工具記憶;檢查不判定存放位置"
71
99
 
72
100
  # ── R5 vs turn-completion-integrity:掛同一事件,行為刻意相反 ──────────────
73
101
  vs_turn_completion_integrity:
@@ -86,6 +114,16 @@ standard:
86
114
  開放工作非空幾乎永遠為真,所以本標準的確認點被設計成永不保留控制權。
87
115
  ordering_when_co_located: "本標準先回報(OWT-009),即使該回合隨後被 TCI 擋下,回報仍然可見"
88
116
 
117
+ # ── 摘要由誰產生(OWT-007 的說明,1.4.0;不新增要求、不新增檢查)─────────────
118
+ summary_production:
119
+ owt_007_does_not_say: "誰產生摘要、摘要多長"
120
+ cheap_way: "由程式在回合結束時印出簡短摘要(掛在回合結束事件上的既有機制執行一個指令,不消耗模型 token),完整版在讀的人要看時才產生"
121
+ expensive_way: "由模型在每則回覆裡手工附一張完整的表:可行、滿足 OWT-007,但昂貴,不是本標準要求的做法"
122
+ still_applies: "OWT-008 與 OWT-009:程式只回報、永不阻斷,輸出排在任何阻斷式檢查的判決之前"
123
+ suggested_vocabulary: ["等人決策", "等外部(對方回覆)", "等 CI", "固定日期到期", "無人看管"] # 建議,非要求
124
+ external_example: "有一個採用專案這樣做;其檔案是私有的,所以不放連結;不屬於 UDS 套件,不保證相容"
125
+ honest_note: "UDS 沒有出貨任何產生 OWT-007 摘要的程式,本標準也沒有東西檢查它存在;本段不新增要求編號、不新增檢查"
126
+
89
127
  # ── 錨點:走訪結構,不走訪措辭(與 DEX-007/DEX-008 同形狀)───────────────
90
128
  anchors:
91
129
  principle: "判定等待中/未分類/已丟棄,讀承載庫自己描述該狀態的結構欄位——狀態欄、型別化標記、小節標題——而非散文措辭"
@@ -134,10 +172,22 @@ standard:
134
172
  why: "與一個弄丟它的 bug 無從分辨"
135
173
  - pattern: "目標或驗收條件被改了,卻沒有「誰同意」的紀錄"
136
174
  why: "「每一條驗收都滿足」依然為真,只是針對另一組條件;被改過的目標讀起來像一直這麼寫"
137
- - pattern: "把手寫的狀態檔當成狀態真相"
175
+ - pattern: "把手寫的狀態檔當成版本控制或 CI 早已知道之事的真相"
138
176
  why: "會過期,而比過期內容新的戳看不見"
139
177
  - pattern: "下一步寫「繼續實作」或「處理剩下的」"
140
178
  why: "沒有點名任何可以開始的東西;與被遺忘的項目無從分辨"
179
+ - pattern: "等待項目沒有任何「有沒有人問過」的紀錄"
180
+ why: "沒人送出的草稿與沒人回的請求看起來一模一樣;等待永遠不會讓前者解除"
181
+ - pattern: "手寫的「已寄出/已回覆/已核准」,沒有名字也沒有日期"
182
+ why: "與猜測無從分辨,過期時也沒有任何東西顯示"
183
+ - pattern: "一個沒有人能做的觀察,被算成「否」或已完成"
184
+ why: "看不到的事實被讀成不存在或已完成;unknown 是一個值,不是零"
185
+ - pattern: "對另一個專案的等待,用某一台機器的目錄記下來"
186
+ why: "換一台機器就是錯的、洩漏使用者名稱,同一份載體的兩個讀者也不再指同一個專案"
187
+ - pattern: "這台機器看不到的專案,被算成已解除或零"
188
+ why: "沒看過的被讀成做完了;「從這裡看不到」是它自己的一個計數"
189
+ - pattern: "等著另一個專案的工作,只放在某個人的 AI 工具記憶裡"
190
+ why: "另一個 session 與 CI 讀不到,檢查也沒有任何具名的載體可以判定"
141
191
 
142
192
  rules:
143
193
  - id: OWT-001
@@ -197,9 +247,49 @@ standard:
197
247
  severity: error
198
248
  severity_rationale: "失效是靜默的,而它只有一個時刻能被抓到——修改發生的那一刻;事後只剩被改過的文字可讀"
199
249
  - id: OWT-019
200
- rule: "「下一步」欄位至少點名一個具體對象:檔案路徑、測試名稱、指令或需求編號之一;只有動詞不算。判定的是有沒有點名對象,不是措辭好壞"
250
+ rule: "「下一步」欄位至少點名一個具體對象:檔案路徑、測試名稱、指令或需求編號之一;只有動詞不算。判定的是有沒有點名對象,不是措辭好壞。處於 asked-awaiting 並滿足 OWT-022 的項目不在這裡判定:它的下一步可以就是它等的那個回覆,由 OWT-022 判定(何時問的、在等什麼、什麼事件解除它)"
201
251
  severity: warning
202
252
  severity_rationale: "「有點名對象」的結構檢查必然粗糙(被點名的對象仍可能無關),違反的代價是下一個工作階段的時間,不是工作本身"
253
+ - id: OWT-020
254
+ rule: "標為等待中的項目說明自己處於兩個狀態中的哪一個:not-yet-asked(請求已草擬或已決定要問,尚未送出)或 asked-awaiting(已送出、還沒有回音);兩者皆非的等待項目,在開放工作摘要裡被個別點名,不被併入總數、不被算成已完成"
255
+ severity: warning
256
+ severity_rationale: "狀態詞與欄位名是第一版詞彙,沒有量測支持(OWT-016);違反的代價是讀的人的時間。更嚴會讓所有早於這兩個狀態的載體在發布當天變紅"
257
+ - id: OWT-021
258
+ rule: "not-yet-asked 的項目點名那份草稿或那個動作(送出它就是解除條件):檔案路徑、指令、測試名稱或需求編號之一(沿用 OWT-019 的辨認)"
259
+ severity: warning
260
+ severity_rationale: "與 OWT-019 同理:「有點名對象」的檢查必然粗糙,違反的代價是下一個工作階段的時間"
261
+ - id: OWT-022
262
+ rule: "asked-awaiting 的項目帶 asked-at(含年份的日曆日、不晚於今天),並滿足 OWT-002:在等什麼、什麼事件算解除"
263
+ severity: warning
264
+ severity_rationale: "asked-at 讓時鐘開始走;缺它的代價是項目沒有年齡、無法被門檻再次浮現,但不是工作本身遺失"
265
+ - id: OWT-023
266
+ rule: "手寫列只容許用在承載庫無法從版控、規格標記或 CI 結果推導的事實;每一列帶 observed-by(誰或什麼看到)、observed-at(含年份的日曆日、不晚於今天)與 yes/no/unknown 的值,缺任一項即違反。檢查只判定欄位存在且格式正確,絕不判定觀察為真"
267
+ severity: warning
268
+ severity_rationale: "這是對 OWT-003 的窄例外,詞彙未校準;它判定的是欄位存在,不是觀察誠實,所以違反的傷害是間接的"
269
+ - id: OWT-024
270
+ rule: "unknown 是值,不是空白:值為 unknown 的列在任何摘要裡單獨計數、單獨顯示,永遠不被算成完成;標為完成而值是 unknown 的列即違反"
271
+ severity: warning
272
+ severity_rationale: "OWT-006 的延伸(看不到的不是零);詞彙未校準,故 warning"
273
+ - id: OWT-025
274
+ rule: "觀察的彙總顯示每筆觀察的年齡;超過宣告門檻的觀察回報為「觀察已舊」、另計、不被算成已確認。戳只說誰何時看到,不說現在仍然如此"
275
+ severity: warning
276
+ severity_rationale: "門檻的預設(7 天)是初始判斷,沒有量測支持(OWT-016)"
277
+ - id: OWT-026
278
+ rule: "OWT-023 的例外不及於版控、規格標記或 CI 結果已能決定的欄位;OWT-003 仍成立。檢查只能拿一份這類主題的詞表判定,其涵蓋率未知(OWT-011)"
279
+ severity: warning
280
+ severity_rationale: "判定靠措辭詞表,必然漏;乾淨的通過不代表沒有可推導的手寫列"
281
+ - id: OWT-027
282
+ rule: "等待項目的解除條件(OWT-002)可以點名另一個專案裡的物件,寫成 <專案>:<物件>。專案是邏輯名稱(uds、vibeops),不是目錄;物件是檔案路徑、測試名稱、指令或需求編號(OWT-019 的辨認)或版本控制標籤;載體裡沒有任何機器專屬的絕對路徑。名稱在某台機器上對應哪個目錄,宣告在載體之外。在等這種物件的項目沒有可被問的請求,所以 OWT-020 的兩個狀態不適用於它"
283
+ severity: warning
284
+ severity_rationale: "名稱樣式、機器專屬路徑前綴清單是第一版判斷(OWT-016),涵蓋率未知(OWT-011);違反的代價是紀錄在另一台機器上失效,不是工作本身遺失"
285
+ - id: OWT-028
286
+ rule: "對每一個這樣的解除條件,檢查回報四種之一並單獨計數、絕不合併:已解除(該物件現在在對方專案裡存在)、尚未解除(專案看得到、物件不在)、從這裡看不到(這台機器看不到那個專案:不是已解除,也不是零)、需要人判斷(專案看得到,但這類物件——測試名稱、指令、需求編號——沒有任何檢查讀得到的東西)。查找只讀本機檔案與版本控制,不開任何網路連線"
287
+ severity: warning
288
+ severity_rationale: "OWT-006 的延伸(看不到的不是零);能查找的物件種類只有路徑與標籤,是初始判斷(OWT-016)"
289
+ - id: OWT-029
290
+ rule: "等著另一個專案的工作,其紀錄是受版本控制、每個相關專案的 session 都讀得到的 repo 裡的一個檔案;不得只放在個人的 AI 工具記憶裡(它綁一個使用者、一台機器,另一個 session 與 CI 讀不到)。用哪個 repo 是採用專案的選擇。參考檢查不判定載體放在哪裡"
291
+ severity: warning
292
+ severity_rationale: "存放位置是採用專案的決定;違反的代價是另一個 session 看不到那份等待,但不是工作本身遺失"
203
293
 
204
294
  # ── 意圖 vs 進度(OWT-017/018/019)──────────────────────────────────────
205
295
  intent_vs_progress:
@@ -217,17 +307,93 @@ standard:
217
307
  - named_and_resolved
218
308
  - named_unresolved
219
309
  - unnamed # 唯一的違反
310
+ - waiting_on_reply # 1.4.0:asked-awaiting 且 OWT-022 齊全;不是違反、不算已點名、不算完成
311
+ waiting_on_reply:
312
+ applies_when: "項目是 asked-awaiting,而且 OWT-020 與 OWT-022 對它沒有任何違反(asked-at 為含年份、不晚於今天的日期;寫了在等什麼;寫了解除事件)"
313
+ judged_by: "OWT-022,不是 OWT-019;next-action 以 waiting 所用的同一個函式(同一個日期)讀該列的狀態,不另寫一份"
314
+ reported_as: "單獨計數(計數行尾附 waiting-on-reply=N,N 為 0 時不印)、自己的一節(列名、年齡、在等什麼、解除條件)、不算已點名、不算完成"
315
+ stale: "年齡超過宣告門檻者標為已舊;沿用 OWT-025 的預設 7 天(--stale-after 宣告),未校準;只標示,不影響結束碼"
316
+ not_waived:
317
+ - "沒有 asked-at、asked-at 不是日期、asked-at 在未來"
318
+ - "沒寫在等什麼、沒寫解除事件"
319
+ - "not-yet-asked(它的下一步是送出草稿,OWT-021 要求點名草稿)"
320
+ - "其他狀態(含 waiting 卻沒說問過沒有)"
321
+ - "寫成小節標題的下一步(沒有狀態欄的一列可言)"
322
+ - "沒有狀態欄的載體(讀法與 1.3.0 完全相同)"
323
+ invariant: "對任一列:waiting 判為 asked-awaiting 且沒有 OWT-020/OWT-022 違反 ⇔ next-action 判為 waiting-on-reply;waiting 對它報 OWT-022 時,next-action 不得免除它"
324
+ exit_code_change: "含這種列的載體,next-action 對該列不再回 1(過去因未點名回 1)"
325
+ not_decidable_by_a_check: "請求是否真的送出、是否仍未回覆——只判定欄位存在且格式正確(OWT-014,同 OWT-023)"
220
326
  coverage: "辨認路徑/指令/測試名稱/編號本身是樣式比對,涵蓋率未知(OWT-011);認不出的格式回報為未點名"
221
327
  fields_read: "參考程序以同一份詞彙讀三種形狀:小節標題、行內標籤、表頭在詞彙內的表格欄(該欄每一列各算一個欄位)"
222
328
  ragged_table_row: "欄數與表頭不一致的列列為判定不了、不當成空白;別處沒有違反時結束碼為 2(不是通過)"
223
329
  empty_field: "空白、—、-、已完成的儲存格只計數不評估,不算違反(OWT-019 判斷寫了的下一步,沒寫是另一種失效)"
224
330
 
331
+ # ── 兩個等待前狀態與助理看不到的事實(OWT-020~026,1.2.0)────────────────
332
+ waiting_and_observed:
333
+ states:
334
+ not_yet_asked:
335
+ meaning: "請求已草擬或已決定要問,尚未送出"
336
+ must_name: "那份草稿或那個動作(檔案路徑、指令、測試名稱或需求編號;沿用 OWT-019 的辨認)"
337
+ released_by: "送出"
338
+ asked_awaiting:
339
+ meaning: "已送出,還沒有回音"
340
+ must_carry: [asked_at, waiting_for, release_event] # 後兩者即 OWT-002
341
+ neither: "標為等待卻不屬於這兩者:被個別點名(比照 OWT-012),不併入總數,不算已完成"
342
+ observed_fact:
343
+ admitted_only_for: "承載庫無法從版控、規格標記或 CI 結果推導的事實(例:是否已寄出、對方是否已回覆、是否已核准)"
344
+ row_fields: [observed_by, observed_at, value]
345
+ value_domain: [yes, no, unknown]
346
+ unknown: "正式的值:單獨計數、單獨顯示、永遠不算完成;標為完成而值是 unknown 即違反"
347
+ age: "每筆觀察顯示年齡;超過宣告門檻者為「觀察已舊」,另計,不算已確認"
348
+ stamp_claims: "誰、何時看到;不宣稱現在仍然如此"
349
+ not_reaching: "版控、規格標記或 CI 結果已能決定的欄位(OWT-003 仍成立)"
350
+ decidable_by_a_check: "欄位是否存在、日期是否為含年份的真實日子且不晚於今天、值是否在值域內、年齡、狀態詞"
351
+ not_decidable_by_a_check: "observed-by 填的是不是真的去看過的人、值是否為真、以及它現在是否仍然如此——這是關於世界的宣稱,不是 artefact 之間的關係(OWT-014)"
352
+ coverage: "狀態詞與欄位名(中英文)、可推導主題詞表皆為措辭比對,涵蓋率未知(OWT-011);沒有 observed-by 也沒有 observed-at 欄的表格不被讀成觀察載體"
353
+ time: "今天的日期由 --now 注入,絕不在規則裡讀時鐘;門檻由 --stale-after 宣告,預設 7 天為未校準的初始判斷(OWT-016)"
354
+ exit_codes: "任何違反(含 warning 等級)結束碼為 1;判定不了為 2(不是通過)"
355
+
356
+ # ── 對另一個專案的等待(OWT-027~029,1.3.0)──────────────────────────────
357
+ cross_project_waiting:
358
+ reference_form: "<專案>:<物件>,專案是邏輯名稱(小寫字母、數字、- 與 _,以字母開頭,2 到 32 字元),物件是檔案路徑、測試名稱、指令、需求編號或版本控制標籤"
359
+ carrier_must_not_hold: "機器專屬的絕對路徑(家目錄與磁碟區目錄、磁碟機代號、~/、UNC 路徑、file: URL)與離開該專案的路徑(..)"
360
+ name_to_directory: "宣告在載體之外:參考檢查的 --root NAME=DIR(可重複,與單一 --root DIR 並存),或採用專案設定的 open_work.projects"
361
+ answers: [released, not_yet_released, not_visible_from_here, needs_a_person]
362
+ not_visible_from_here: "這台機器看不到該專案(沒有宣告目錄、目錄不存在、讀不到版本控制):單獨計數,不是已解除,也不是零"
363
+ machine_observable: "檔案路徑(存在與否)與版本控制標籤(存在與否);其餘種類回報為需要人判斷"
364
+ waiting_state: "在等另一個專案之物件的項目免於 OWT-020 的兩個狀態,單獨計數為 waiting-cross-project,仍被點名"
365
+ record_location: "受版本控制、每個相關專案的 session 都讀得到的 repo;不得只放個人 AI 工具記憶;檢查不判定(OWT-029)"
366
+ scope: "一個人在一台機器上的各個 session;跨人共享與共享紀錄的審核不在本版決定"
367
+ decidable_by_a_check: "邏輯名稱樣式、有無機器專屬路徑、路徑或標籤在本機是否存在"
368
+ not_decidable_by_a_check: "被點名的物件是不是對的那一個、測試或指令是否通過、紀錄存在哪個 repo、誰讀得到(OWT-014)"
369
+ network: "不連網:只讀本機檔案與 git"
370
+
371
+ # ── 「下一步」詞彙(461,併入 1.3.0,不新增要求編號)────────────────────────
372
+ next_action_words:
373
+ one_list: "一份清單,三種讀法(標題、表頭、行內標籤),沒有第二份;採用者宣告的詞併入同一份"
374
+ built_in: ["next action/next step", "下一步", "下一動", "回來要做什麼", "下一個動作", "下一個步驟", "接下來要做什麼"]
375
+ deliberately_absent: ["待辦", "後續", "Next", "TODO", "Action", "接下來"]
376
+ why_absent: "這些詞也標在不是下一步的欄位上;讀成下一步會讓違反藏在一個從來不是下一步的欄位後面"
377
+ declared_by_adopter: "--next-action-word WORD(可重複),或採用專案設定的 open_work.next_action_words;兩者合併"
378
+ declared_word_is: "純文字、不分大小寫、子字串比對,不是正規表達式;空字串或只有空白被拒絕並說明,不被靜默忽略"
379
+ exit_2_explains: "完全找不到欄位時結束碼仍是 2;訊息列出每個載體看到的表頭與標題(約 20 個)、認得的詞(宣告的另列)、怎麼加,並分辨「有表格但表頭都不符」與「沒有表格也沒有標題可讀」"
380
+ uncalibrated: "內建清單與它拒絕收的詞都是初始判斷(OWT-016)"
381
+ command_words:
382
+ built_in_additions: ["glab", "dotnet"]
383
+ deliberately_absent: ["go", "make", "sh"]
384
+ declared_by_adopter: "--command-word PROGRAM(可重複),或採用專案設定的 open_work.command_words;next-action 與 waiting 都讀"
385
+ rule: "一個程式名,純文字、區分大小寫、不是正規表達式;空白或含空格的詞被拒絕並說明"
386
+ resolution_is_said:
387
+ what: "next-action 說路徑是在哪個目錄下查找的、那個目錄從哪來(--root 或目前目錄),載體在 git repo 之外又沒給 --root 時明說"
388
+ only_paths: "只有路徑會被查找;指令、測試名稱、需求編號只判定有沒有被指名,永遠不會是已解析"
389
+ split: "named-unresolved 分成 path-missing(查過、不在)與 not-resolvable(從不查找);兩者相加等於 named-unresolved,既有輸出行不變,只新增行"
390
+
225
391
  # ── 刻意不採納(來源:使用者轉貼的提示詞,作者不明,僅借設計形狀)──────────
226
392
  not_adopted:
227
393
  source: "使用者轉貼的提示詞,作者與出處不明、無實作;僅借設計形狀,不引用其任何宣稱"
228
394
  items:
229
- - what: "以手寫狀態檔作為狀態真相"
230
- why: "手寫狀態會過期,而戳比過期內容新是隱形的(OWT-004/005 的起因);只說以版本控制為準卻沒有對帳機制,就是採納一個已知會過期的來源。OWT-003 已要求可推導的欄位改用生成"
395
+ - what: "以手寫狀態檔作為任何「已有可靠來源可決定」之狀態的真相"
396
+ why: "手寫狀態會過期,而戳比過期內容新是隱形的(OWT-004/005 的起因);只說以版本控制為準卻沒有對帳機制,就是採納一個已知會過期的來源。OWT-003 已要求可推導的欄位改用生成。自 1.2.0 起有一個窄例外(OWT-023~026):對沒有任何東西能推導的事實(訊息是否已寄出、對方是否已回覆),容許一列手寫——但必須附誰何時看到的戳記、值可以誠實是 unknown、且每份報告都顯示年齡,並且絕不及於版控、規格標記或 CI 結果已能決定的欄位。上面的反對理由是被回答了,不是被擱置:那個理由是過期看不見,而這裡年齡就印在每個值旁邊"
231
397
  - what: "固定的開工儀式(讀檔→查版本控制→驗證)"
232
398
  why: "交接點已由 OWT-007 與 turn-completion-integrity 管住;開工儀式要靠各代理工具自己的指示設定,寫進標準只會得到一條沒有任何 artefact 檢查判定得了的要求(違反 OWT-014)"
233
399
 
@@ -235,10 +401,11 @@ standard:
235
401
  enforcement:
236
402
  automated_gate: false
237
403
  reference_check:
238
- command: "uds open-work <next-action|revision|separation|self-test>" # 隨 npm 安裝包出貨,採用者不需要 clone
404
+ command: "uds open-work <next-action|revision|separation|waiting|observations|self-test>" # 隨 npm 安裝包出貨,採用者不需要 clone
239
405
  path: cli/src/utils/open-work-tracking.mjs # 規則本體只有這一份
240
406
  repo_entry: scripts/check-open-work-tracking.mjs # 只在 UDS repo 副本裡的薄殼,不含規則
241
- covers: [OWT-017, OWT-018, OWT-019]
407
+ next_action_options_1_4_0: "--now YYYY-MM-DD 與 --stale-after DAYS(與 waiting/observations 同義);next-action 以 waiting 的同一個函式讀每一列的狀態"
408
+ covers: [OWT-017, OWT-018, OWT-019, OWT-020, OWT-021, OWT-022, OWT-023, OWT-024, OWT-025, OWT-026, OWT-027, OWT-028] # OWT-029 靠採用專案自己決定,檢查不判定
242
409
  status: "參考判定程序,作為 OWT-015 意義上的證據(已對違反樣本紅過);不是閘門,未接進任何 UDS 發版閘門,因為 UDS 沒有承載開放工作的地方可供檢查"
243
410
  why_not: >
244
411
  依上面的寫法約束,UDS 陳述關係,有沒有東西判定它是採用專案的決定。
@@ -259,6 +426,15 @@ standard:
259
426
  added_in_1_1_0:
260
427
  origin: "DEC-122(2026-09-29):一個採用專案裡,目標與進度沒分開、且一條驗收條件被改而無人核可紀錄;設計形狀借自使用者轉貼、作者不明的提示詞"
261
428
  uncalibrated_per_owt_016: "參考判定程序用的標題詞彙、指令名清單、副檔名清單、需求編號樣式——全是初始判斷,沒有對照真實使用量測;採用專案應傳入自己的"
429
+ added_in_1_2_0:
430
+ origin: "XSPEC-459(2026-10-07):一個採用專案對 6.14.0-beta.5 的測試回報——草擬了從沒送出的訊息與已送出、沒人回的訊息分不出來;助理無法觀察的事實沒有被認可的存放處"
431
+ uncalibrated_per_owt_016: "中英文的狀態詞與欄位名、被當成可推導的主題詞表、「觀察已舊」預設的 7 天、日期的讀法(必須有年份、時間不看)——全是初始判斷,沒有對照真實使用量測;參考判定程序只有幾小時大、跑過的是人造樣本"
432
+ added_in_1_3_0:
433
+ origin: "XSPEC-460/XSPEC-461(2026-10-07):一個專案的項目在等另一個專案的產出,當時只有臨時約定;另有使用者的載體一個狀態一張表,next-action 回 2 卻沒說為什麼"
434
+ uncalibrated_per_owt_016: "邏輯名稱樣式、機器專屬路徑前綴、能查找的物件種類(路徑與標籤)、「下一步」內建詞與它拒絕收的詞——全是初始判斷,沒有對照真實使用量測;參考判定程序只有幾小時大、跑過的是人造樣本"
435
+ added_in_1_4_0:
436
+ origin: "XSPEC-464(2026-10-07):同一個採用專案對 6.14.0-beta.5 的測試——17 個下一步欄位中 14 個是「等對方回信/排時間/撤銷」,waiting 接受而 next-action 拒絕同一批列;該專案拒絕只為通過檢查而改寫載體"
437
+ uncalibrated_per_owt_016: "「已舊」沿用 OWT-025 的 7 天預設(未經量測)、判定 asked-awaiting 的狀態詞(同 OWT-020)——全是初始判斷;只寫了解除條件、沒寫問的日期的載體,補上日期之前仍由 OWT-019 判定"
262
438
  recalibration: "由採用專案自行決定與自行訂定時程;本標準不承諾覆核日期,如同它不承諾閘門"
263
439
 
264
440
  related:
@@ -283,4 +459,8 @@ physical_spec:
283
459
  - "超過門檻仍未分類項目的個別點名,與已丟棄項目的一句理由"
284
460
  - "目標/驗收條件與進度/下一步分屬不同載體(以結構判定)"
285
461
  - "目標或驗收條件的每次修改對應一筆「改了什麼、誰核可、為什麼」紀錄;無核可者的修改在交回點被列出"
286
- - "每個「下一步」點名至少一個檔案路徑、測試名稱、指令或需求編號"
462
+ - "每個「下一步」點名至少一個檔案路徑、測試名稱、指令或需求編號;已問、等回覆且 OWT-022 齊全的項目除外,它的下一步可以就是那個回覆(單獨列出、顯示年齡)"
463
+ - "每個等待項目標明「還沒問」或「已問、等回覆」;還沒問的點名草稿,已問的帶 asked-at、等什麼與解除事件"
464
+ - "助理看不到的事實的手寫列:observed-by、observed-at、yes/no/unknown 的值;unknown 與「觀察已舊」另計、永不算完成;每筆顯示年齡"
465
+ - "等著另一個專案的項目用 <專案>:<物件> 點名,載體沒有機器專屬路徑;每個這樣的條件回報已解除/尚未解除/從這裡看不到/需要人判斷之一,看不到的單獨計數"
466
+ - "等著另一個專案的工作,紀錄放在受版本控制、各方 session 都讀得到的 repo,不只放個人 AI 工具記憶"
@@ -8,7 +8,7 @@
8
8
  standard:
9
9
  id: pipeline-security-gates
10
10
  name: Pipeline Security Gates
11
- description: Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan with block/warn/log behavior
11
+ description: Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan (including the scanner's own output and failure behaviour) with block/warn/log behavior
12
12
  guidelines:
13
13
  - "Secrets scan at pre-commit — block ALL commits containing secrets"
14
14
  - "SAST after build — block Critical/High findings"
@@ -17,10 +17,13 @@ standard:
17
17
  - "DAST after staging deploy — warn on findings, require approval for Critical"
18
18
  - "Never skip security gates with --force or emergency bypass without audit trail"
19
19
  - "Treat security gate failures as pipeline failures, not warnings"
20
+ - "Secrets-scan output (terminal, CI log, report file) MUST NOT contain the matched secret value — name the file, line and rule only (PSG-1)"
21
+ - "A secrets scanner that cannot run (missing binary, unreadable or invalid config, timeout, unexpected exit) is a gate failure and MUST block — never swallow it with `|| true` or `2>/dev/null` (PSG-2)"
22
+ - "SHOULD: every detection rule the team writes itself has one red sample (must match) and one green sample (must not match), run in tests (PSG-3)"
20
23
 
21
24
  meta:
22
- version: "1.0.0"
23
- updated: "2026-04-26"
25
+ version: "1.1.0"
26
+ updated: "2026-10-07"
24
27
  source: core/pipeline-security-gates.md
25
28
  complements: security-standards.ai.yaml
26
29
 
@@ -31,6 +34,48 @@ gate_positions:
31
34
  scope: "staged files"
32
35
  block_on: ["any secret pattern match"]
33
36
  never_skip: true
37
+ # Added in 1.1.0 (XSPEC-463): the scanner's own behaviour. UDS ships no scanner —
38
+ # these are properties the adopter verifies on their own gate, by the procedures below.
39
+ output_redaction: # PSG-1
40
+ level: must
41
+ rule: "scan output must not contain the matched secret value; name file, line and rule only"
42
+ surfaces: ["terminal", "ci log", "report file"]
43
+ reason: "scan logs get pasted into chat and tickets; printing the value leaks an already-blocked secret a second time"
44
+ tool_notes:
45
+ gitleaks: "official README (read 2026-10-07): sample output of `gitleaks git -v` without --redact prints a `Secret:` line with the matched value; --redact is described as 'redact secrets from logs and stdout'; the README does not say whether it also covers --report-path files — adopter must confirm"
46
+ detect-secrets: "default output behaviour not verified by this standard — adopter must confirm"
47
+ trufflehog: "default output behaviour not verified by this standard — adopter must confirm"
48
+ verification:
49
+ - "stage a file containing a FAKE secret in a format the adopter's own gate matches (FAKE-SECRET-DO-NOT-USE-0000 is notation only; never a valid credential for any real service) and run the gate"
50
+ - "first confirm the gate really blocked — if it did not, the sample was not matched and step 3 proves nothing"
51
+ - "search ALL output (terminal, ci log, report file) for the fake string; any hit is non-compliant"
52
+ scanner_failure: # PSG-2
53
+ level: must
54
+ treat_as: gate_failure
55
+ action: block
56
+ covers: ["executable missing", "config unreadable or invalid", "timeout", "unexpected exit"]
57
+ forbidden_swallow: ["|| true", "2>/dev/null"]
58
+ distinguish_cause_by: output # not by exit code
59
+ tool_notes:
60
+ gitleaks: "official README, Exit Codes (read 2026-10-07): `1 - leaks or error encountered` — a finding and an error share exit code 1, so tell them apart by output; --exit-code can rewrite the exit code for findings, never set it to 0"
61
+ detect-secrets: "exit-code behaviour not verified by this standard — adopter must confirm"
62
+ trufflehog: "exit-code behaviour not verified by this standard — adopter must confirm"
63
+ precedent: "UDS native .git/hooks/pre-commit once chained every check with `2>/dev/null || true` and printed 'passed' (fixed in 6.14.0-beta.4, see CHANGELOG)"
64
+ verification:
65
+ - "rename or remove the scanner executable, or make its config invalid"
66
+ - "run the gate on a commit that contains no secret (any block can then only be the scanner failing to run)"
67
+ - "pass = blocked, non-zero exit, output says the scanner could not run; a commit let through, or output that reads like a pass, is non-compliant"
68
+ custom_rule_samples: # PSG-3
69
+ level: should
70
+ applies_to: "detection rules the team wrote itself, including the REQ-003 minimum four (AWS access key, PEM private key header, generic API token, connection string with password); not to teams using only built-in rules"
71
+ per_rule: ["one red sample that must match", "one green sample that must not match"]
72
+ samples_run_in_tests: true
73
+ principle: "OWT-015 — a check never observed red is not evidence"
74
+ gap_blocks: false # SHOULD: a missing sample is a reported gap, not a block
75
+ verification:
76
+ - "list every self-written rule"
77
+ - "find each rule's red and green sample (fake values)"
78
+ - "confirm the samples really run in tests; a missing one is a gap"
34
79
  post_build:
35
80
  type: sast
36
81
  tools: ["semgrep", "codeql", "sonarqube"]
@@ -10,13 +10,23 @@ standard:
10
10
  - "Inject context proactively during planning and coding phases based on file scope"
11
11
  - "Store entries as Markdown files with YAML Frontmatter in .project-context/"
12
12
  - "Use identified paths and specific names (unlike Developer Memory)"
13
+ - "Keep personal, cross-project, identifiable facts and cross-project work coordination out of the repository's project context (see boundary)"
13
14
 
14
15
  meta:
15
- version: "1.2.0"
16
- updated: "2026-06-18"
16
+ version: "1.2.1"
17
+ updated: "2026-10-07"
17
18
  source: core/project-context-memory.md
18
19
  description: System for capturing, retrieving, and enforcing project-specific context, architectural decisions, and domain knowledge
19
20
 
21
+ boundary:
22
+ not_held_here:
23
+ - what: "個人、跨專案、可識別的資訊(誰負責什麼、怎麼連到某個環境)"
24
+ belongs_in: "使用者自己的 AI 工具記憶"
25
+ why: "專案情境在 repo 裡,會被每個 clone 它的人看到;這類資訊不是專案情境"
26
+ - what: "跨專案的工作協調(誰在等誰)"
27
+ belongs_in: "open-work-tracking(OWT-027~OWT-029)"
28
+ why: "那是開放工作,不是情境"
29
+
20
30
  schema:
21
31
  format: "Markdown with YAML Frontmatter"
22
32
  required:
@@ -2,8 +2,8 @@
2
2
 
3
3
  > **Language**: English | [繁體中文](../locales/zh-TW/core/code-review-checklist.md)
4
4
 
5
- **Version**: 1.5.0
6
- **Last Updated**: 2026-08-24
5
+ **Version**: 1.6.0
6
+ **Last Updated**: 2026-10-08
7
7
  **Applicability**: All software projects with code review processes
8
8
  **Scope**: universal
9
9
  **Industry Standards**: SWEBOK v4.0 Chapter 10
@@ -141,6 +141,7 @@ This standard provides a comprehensive checklist for reviewing code changes, ens
141
141
  - Test names describe scenarios
142
142
  - Assertions are clear
143
143
  - No flaky tests
144
+ - Expected values are independent of the code under test: a literal, a hand-computed example or the spec — not the same call repeated, not the same arithmetic typed again (see [Forbidden: Tautology Assertions](full-coverage-testing.md))
144
145
 
145
146
  - [ ] **Test coverage maintained**
146
147
  - Coverage not decreased
@@ -247,6 +248,19 @@ This standard provides a comprehensive checklist for reviewing code changes, ens
247
248
 
248
249
  ---
249
250
 
251
+ ### 11. Merge Danger (Reversibility)
252
+
253
+ - [ ] **The change states its door and its blast radius**
254
+ - **Two-way door**: after merging, it can be taken back easily
255
+ - **One-way door**: it cannot be undone, or only with difficulty — a data migration, a deletion, a changed default behavior, a changed exit code, a renamed public interface
256
+ - **Blast radius**: one word for how far it reaches (for example `docs`, `cli`, `adopters`)
257
+
258
+ - [ ] **A one-way door is known to the decision-maker before the merge**
259
+ - Whoever decides to merge has been told, in the PR description or the hand-off report, that this change cannot be easily undone
260
+ - If the field is missing, ask for it; do not infer the door from the diff alone
261
+
262
+ ---
263
+
250
264
  ## Review Comment Types
251
265
 
252
266
  Use these prefixes to clarify comment intent:
@@ -320,6 +334,7 @@ For teams preferring plain text labels without emojis:
320
334
  1. Read PR description and linked issues
321
335
  2. Understand WHY the change is needed
322
336
  3. Review design/spec documents if linked
337
+ 4. Read the Merge Danger field (door and blast radius); for a one-way door, confirm the decision-maker knows before merging
323
338
 
324
339
  #### Step 2: High-Level Review
325
340
 
@@ -357,6 +372,7 @@ For teams preferring plain text labels without emojis:
357
372
  2. **Run tests locally**
358
373
  3. **Check CI status**
359
374
  4. **Write clear PR description**
375
+ 5. **State the Merge Danger** — door (two-way or one-way) and blast radius, in one word
360
376
 
361
377
  #### During Review
362
378
 
@@ -650,6 +666,7 @@ All PRs must pass:
650
666
  │ ✓ Errors - Properly handled? │
651
667
  │ ✓ Docs - Updated? │
652
668
  │ ✓ Dependencies - Necessary? │
669
+ │ ✓ Merge danger - One-way door told? │
653
670
  └─────────────────────────────────────────┘
654
671
 
655
672
  Comment Prefixes:
@@ -666,6 +683,7 @@ Comment Prefixes:
666
683
 
667
684
  | Version | Date | Changes |
668
685
  |---------|------|---------|
686
+ | 1.6.0 | 2026-10-08 | Added: Merge Danger (door and blast radius) as checklist item 11 and in the reviewer/author steps — a one-way door must be known to the decision-maker before merge; added to "Tests are good quality" that expected values are independent of the code under test (XSPEC-470 R1, R2) |
669
687
  | 1.5.0 | 2026-08-24 | Added: pointer to `deferred-item-exit` for non-blocking comments accepted without a change (XSPEC-391 R5) |
670
688
  | 1.4.0 | 2026-06-18 | Added: source + configurability note for PR-size/response-time thresholds (SmartBear/Cisco study, Google practices) + bulk-change exception (XSPEC-292 T8) |
671
689
  | 1.3.0 | 2026-01-12 | Added: Comprehensive Refactoring PRs section with pre-review checklist, review focus areas, large refactoring guidelines, red flags, and best practices |
@@ -2,8 +2,8 @@
2
2
 
3
3
  > **Language**: English | [繁體中文](../locales/zh-TW/core/developer-memory.md)
4
4
 
5
- **Version**: 1.2.0
6
- **Last Updated**: 2026-09-25
5
+ **Version**: 1.2.1
6
+ **Last Updated**: 2026-10-07
7
7
  **Applicability**: All software projects using AI assistants
8
8
  **Scope**: universal
9
9
  **Owning Spec**: XSPEC-291 (developer-memory has no dedicated feature XSPEC; XSPEC-291 owns it)
@@ -641,10 +641,20 @@ A tool without a session-start hook still satisfies this standard through either
641
641
 
642
642
  ---
643
643
 
644
+ ## Boundary: What This Standard Does Not Hold
645
+
646
+ Two kinds of information are outside this standard, and writing them here is a mistake:
647
+
648
+ - **Personal, cross-project, identifiable facts** (who owns what, how to reach a particular environment). De-identification (see the schema above) would strip exactly these, so they cannot live in a memory entry. They belong in the memory of the user's own AI tool, which is bound to that user and that machine and is not shared.
649
+ - **Coordination between projects** (which piece of work is waiting on which other). That is open work, not memory: see [Open Work Tracking](open-work-tracking.md) (OWT-027–OWT-029).
650
+
651
+ ---
652
+
644
653
  ## Version History
645
654
 
646
655
  | Version | Date | Changes |
647
656
  |---------|------|---------|
657
+ | 1.2.1 | 2026-10-07 | Added: a Boundary section — personal, cross-project, identifiable facts and coordination between projects are not memory entries (XSPEC-460 R5; patch, no behavioral change) |
648
658
  | 1.2.0 | 2026-09-25 | Added: `code-reference` staleness check to Review (§3.4) — a memory citing a moved/missing file path or symbol is flagged before surfacing; reuses Knowledge Graph Memory's degraded/engine dual mode instead of inventing a third; `unresolvable` may not be read as present or missing; scope is file paths and symbol names only (`file:line` explicitly out of scope, DEC-115 OQ-1); §11 adds a non-normative Claude Code adoption example (DEC-115-L1) |
649
659
  | 1.1.1 | 2026-06-18 | Added: `Owning Spec` header pointing to XSPEC-291 (patch, no behavioral change; XSPEC-291 §11 disposition) |
650
660
  | 1.1.0 | 2026-06-18 | Added: rationale column + configurable note to Retirement Suggestions thresholds (XSPEC-292 T8) |
@@ -1,7 +1,7 @@
1
1
  # Full Coverage Testing Standards
2
2
 
3
3
  > **AI-optimized version**: `ai/standards/full-coverage-testing.ai.yaml`
4
- > **XSPEC**: XSPEC-178, XSPEC-444 (R2, R5 — pre-commit warnings and shipped gate scripts)
4
+ > **XSPEC**: XSPEC-178, XSPEC-444 (R2, R5 — pre-commit warnings and shipped gate scripts), XSPEC-470 (R1 — tautology means "expected value not independent")
5
5
  > **Replaces**: Pyramid threshold model (UT≥80%, IT≥70%, E2E happy-path-only)
6
6
 
7
7
  ## Overview
@@ -50,18 +50,58 @@ Coverage improved: 91.3% → 92.0%. New baseline set.
50
50
 
51
51
  ### Forbidden: Tautology Assertions
52
52
 
53
- Assertions that always pass regardless of behavior provide false coverage.
53
+ An assertion that cannot disagree with the implementation provides false coverage. There are two kinds:
54
+
55
+ 1. **Always true** — it passes whatever the code does: `expect(true).toBe(true)`, `assert 200 == 200`.
56
+ 2. **Not independent** — the expected value is produced by the code under test, or by the same logic written a second time inside the test. It passes when the implementation is right, and it passes just as well when the implementation and the copy are wrong in the same way.
57
+
58
+ The second kind is defined with the vocabulary of [`verification-oracle`](verification-oracle.md): an assertion's **oracle** is the source that says what the right answer is, and a tautology is an assertion whose oracle *is the implementation itself*. This standard does not define "independent source of truth" a second time; it uses that standard's: a registered ground-truth case, a known literal, a hand-computed example, or the specification (see its *Oracle-ability Spectrum*).
54
59
 
55
60
  ```typescript
56
61
  // ❌ FORBIDDEN — always passes, tests nothing
57
62
  expect(true).toBe(true)
58
63
  expect(result).toBeDefined() // without specific value
59
64
 
60
- // ✅ REQUIRED — verifies actual behavior
65
+ // ❌ FORBIDDEN — the oracle is the implementation
66
+ expect(countInstalled(manifest)).toBe(countInstalled(manifest)) // the same call on both sides
67
+ expect(countInstalled(manifest)).toBe(manifest.standards.filter(s => s.installed).length) // the same logic, typed again
68
+ // ^ a reviewer's call: the scanner catches only the subset listed under "What the shipped scanner decides" below, and this one is not in it
69
+
70
+ // ✅ REQUIRED — a value that was decided before the code ran
61
71
  expect(result).toBe(90)
62
72
  expect(result).toEqual({ discount: 10, total: 90 })
73
+ expect(countInstalled({ standards: [{ id: 'a', installed: true }, { id: 'b', installed: false }] })).toBe(1)
63
74
  ```
64
75
 
76
+ Not every comparison of two computed values is a tautology. These are fine, and are **not** reported:
77
+
78
+ | Looks similar | Why it is a real test |
79
+ |---------------|-----------------------|
80
+ | `expect(snapshot(dir)).toEqual(before)` after an action | Asks "did anything change?" — the two values are taken at different moments |
81
+ | `expect(parse(a)).toEqual(parseWithOldEngine(a))` | A second, independently written implementation is the oracle |
82
+ | `expect(hash(x)).toBe(hash(x))` in a test named for determinism | Comparing two calls is the point of the test |
83
+ | `expect(report.total).toBe(rows.reduce(...))` where `report` comes from a different data path than `rows` | A reconciliation between two sources |
84
+
85
+ #### What the shipped scanner decides, and what stays a reviewer's question
86
+
87
+ `scripts/check-anti-fake-tests.mjs` (see "The two scanners" below) names the two shapes that can be decided from the text alone. It reads **JavaScript/TypeScript** (`toBe`, `toEqual`, `toStrictEqual`, chai `to.equal`/`to.eql`, node `assert.equal`/`strictEqual`/`deepEqual`/`deepStrictEqual`):
88
+
89
+ | Shape | Example | Reported when |
90
+ |-------|---------|---------------|
91
+ | **same call** | `expect(total(items)).toBe(total(items))` | both sides are the same call with the same arguments (and no other call or `new` inside the call), written in one statement, and the test is not named for comparing two calls (determinism, idempotence, caching, identity) |
92
+ | **recomputed** | `expect(total(items)).toBe(items.reduce((s, i) => s + i.price, 0))` | the call under test takes an input, and the expected value runs that same input (named as the argument itself, e.g. `items.reduce`, not a field of it) through `reduce`, `map`, `flatMap` or `filter` with a callback that uses nothing but its own parameters (plus pure built-ins such as `Math`, `Number`, `String`), holds no literal and is not a mere copy (`(x) => x`, `(x) => ({ ...x })`); the call under test is one call with no other call or `new` inside it and nothing after it such as `.length`. Only the text of the assertion is read: a name set on an earlier line is never looked through |
93
+
94
+ These look similar and are **left alone on purpose**, because the text cannot tell them from a sound test: `expect(priceOf(ids)).toEqual(ids.map(id => KNOWN_PRICES[id]))` (the expected value is read from a fixed table, an independent source); `expect(activeOf(users)).toEqual(users.filter(u => u.id === 2))` (the literal is knowledge the test author supplied); `expect(render(now())).toBe(render(now()))` (two calls to `now()` are two values, so the two sides are not known to be equal); `expect(parse(serialize(rows))).toEqual(rows.map(r => r))` (a round trip: there is a call inside the call under test); `expect(clone(input)).toEqual(input.map(x => x))` (a callback that only hands its parameter back, or a shallow copy of it such as `u => ({ ...u })`, or a destructured parameter put straight back in the same shape such as `([k, v]) => [k, v]`, is a copy and not logic; a `filter(x => x)`, which selects by truthiness, is logic, but it is left alone with them because the text cannot tell it from a copy); `expect(sortUsers(users).length).toBe(users.filter(u => u.name).length)` (the value under test is a property of the result, and which side is right cannot be read from the text). `const before = items.map(i => i.price); freezeCart(items); expect(pricesOf(items)).toEqual(before)` (a name set on an earlier line holds a value from an earlier moment, and what happened in between is what the test asks about; the same-call shape is read the same way). The rule is: when in doubt, miss it rather than accuse it.
95
+
96
+ **Two costs that are accepted, not hidden.**
97
+
98
+ 1. **Differential tests are named.** A test that uses a reference implementation as its oracle, `expect(fastTotal(items)).toBe(items.reduce((s, i) => s + i.price, 0))`, looks exactly like the textbook example, so the scanner names it. Such a test is legitimate (see the table above, "a second, independently written implementation"); the ways to settle it are: put one assertion against a hand-computed literal in the same test (a test is reported only when none of its assertions is a real one), or list the file under `ignore` in `.standards/test-policy.json` (this removes the whole file from every check of this scanner, and `ignore` takes no reason, so say why in a comment). A test name such as "matches the reference implementation" does **not** exempt it, and the `exempt` list does not apply to this scanner (it belongs to the code-without-a-test check).
99
+ 2. **The rule is easy to get around.** Wrapping the **value under test** in `Number(...)`, adding `.valueOf()` or `[0]` to it, or passing `items.slice()` instead of `items` is enough to stop the scanner from seeing it. (Doing the same to the **expected** value changes nothing: that is still named.) It is a prompt for the reviewer, not a gate that holds against someone who means to avoid it, and that includes an AI agent writing the test: do not read a clean scan as evidence that the expected values are independent. The reviewer's questions below are the control; the script only points at the cheapest cases.
100
+
101
+ As with `expect(true).toBe(true)`, a test is reported only when **none** of its assertions is a real one; a self-comparison next to an assertion against a literal is left to the reviewer. When the text cannot decide, the scanner stays silent — a scanner that cries wolf is switched off.
102
+
103
+ Everything else is a **reviewer's question**, asked in code review (see [Code Review Checklist](code-review-checklist.md)): Where did this expected value come from? Could it be produced by running the code under test? Would the test still pass if the implementation were wrong in the way the test's own arithmetic is wrong? Typical cases the scanner does not judge: a hand-written loop that re-derives the answer, a helper that wraps the implementation, a snapshot generated from the implementation's own first output, and every language other than JavaScript/TypeScript.
104
+
65
105
  ### Forbidden: Mocking Core Business Logic
66
106
 
67
107
  Mocking your own code means the business logic is never actually executed.
@@ -236,7 +276,7 @@ The rules above used to depend on scripts the standard told you to write yoursel
236
276
 
237
277
  | Script | Finds |
238
278
  |--------|-------|
239
- | `scripts/check-anti-fake-tests.mjs` | a test with **no assertion**; a test whose only assertions are **tautologies** (`expect(true).toBe(true)`, `assert 200 == 200`); a test file in which **every test is skipped or todo** |
279
+ | `scripts/check-anti-fake-tests.mjs` | a test with **no assertion**; a test whose only assertions are **tautologies** (`expect(true).toBe(true)`, `assert 200 == 200`; in JavaScript/TypeScript also an expected value that is the same call as the code under test, or is recomputed from the same input with `reduce`/`map`/`filter` — see "Forbidden: Tautology Assertions"); a test file in which **every test is skipped or todo** |
240
280
  | `scripts/check-stubs.mjs` | `// WARNING: STUB` markers; a body that says it is **not implemented** (`raise NotImplementedError`, `todo!()`, `TODO()` ...) with no marker beside it; a named function whose body is **empty** with no marker beside it |
241
281
 
242
282
  - Pure Node, no dependencies, no test framework assumed. They are **your files**: edit them, wire them into CI. Run on its own, each exits non-zero when it finds something — `node scripts/check-stubs.mjs` is the pre-push/deploy gate this standard's deployment gates describe.