universal-dev-standards 6.14.0 → 6.14.1-beta.1

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.
@@ -10,7 +10,12 @@
10
10
  * or a raw message on stdin. Exit 1 when invalid.
11
11
  * - Claude Code PreToolUse(Bash): the hook payload arrives as JSON on stdin.
12
12
  * Exit 2 blocks the tool call; anything that is not a
13
- * `git commit -m` is none of this hook's business.
13
+ * `git commit` carrying its message on the command line
14
+ * (-m, -am, -mmsg, --message=msg, several -m) is none of
15
+ * this hook's business: -F, -C, --amend --no-edit, the
16
+ * editor, --fixup/--squash and shell-computed messages
17
+ * ($MSG, $(...)) are allowed because the text is not there
18
+ * to judge. The heredoc form is judged by its body.
14
19
  *
15
20
  * 🔴 It was registered on UserPromptSubmit and read stdin as a raw commit
16
21
  * message, so in an adopter's session it ran on EVERY prompt, failed to parse
@@ -93,23 +98,265 @@ function complain(msg) {
93
98
  }
94
99
 
95
100
  /**
96
- * The message of a `git commit -m ...`, or null when this is not one.
101
+ * `git commit -m "$(cat <<'EOF' ... EOF)"`, the form Claude Code itself writes most often. Group 2 is the quote of
102
+ * the delimiter (empty = unquoted, so the shell would still expand `$` in the body), group 4 is the body.
103
+ */
104
+ const HEREDOC_SUBSTITUTION = /^\$\(\s*cat\s+<<(-?)\s*(['"]?)(\w+)\2[ \t]*\n([\s\S]*?)\n[ \t]*\3[ \t]*\n?\s*\)/;
105
+
106
+ /**
107
+ * Split a shell command line into segments (at `&&`, `||`, `;`, `|` and newline that are NOT inside quotes) of
108
+ * words, resolving quotes and backslashes the way a POSIX shell does. A word carries `dynamic: true` when the
109
+ * shell would compute part of it (`$VAR`, `$(...)`, backticks), because then its text is not what git receives.
110
+ *
111
+ * Splitting before honouring quotes was the bug behind three false blocks: a message containing `;` or `&&`,
112
+ * and the `$(cat <<'EOF' ...)` form, whose newlines cut the command in the middle of the message.
97
113
  *
98
- * The command must BE a git commit, not merely mention one: a substring test
99
- * pulled `fake"` out of `echo "git commit -m fake"`. Global options are allowed
100
- * between `git` and `commit` (`git -C /tmp/repo commit -m ...`), which a
101
- * flags-only pattern rejected. Both were caught by this function's own tests.
114
+ * @param {string} command
115
+ * @returns {{ text: string, dynamic: boolean }[][] | null} null when the quoting is unbalanced
116
+ */
117
+ function tokenize(command) {
118
+ const n = command.length;
119
+ const segments = [];
120
+ let words = [];
121
+ let text = '';
122
+ let started = false; // a word is in progress (so `""` is an empty word, not nothing)
123
+ let dynamic = false;
124
+ const add = (s) => { text += s; started = true; };
125
+ const endWord = () => {
126
+ if (started) words.push({ text, dynamic });
127
+ text = ''; started = false; dynamic = false;
128
+ };
129
+ const endSegment = () => {
130
+ endWord();
131
+ if (words.length > 0) segments.push(words);
132
+ words = [];
133
+ };
134
+
135
+ /** `(` at i ... matching `)`: index just after it, or -1. Honours quotes and backslashes inside. */
136
+ const skipParens = (i) => {
137
+ let depth = 0;
138
+ for (let j = i; j < n; j++) {
139
+ const ch = command[j];
140
+ if (ch === '\\') j++;
141
+ else if (ch === "'") { j = command.indexOf("'", j + 1); if (j < 0) return -1; }
142
+ else if (ch === '"') {
143
+ for (j++; j < n && command[j] !== '"'; j++) if (command[j] === '\\') j++;
144
+ if (j >= n) return -1;
145
+ } else if (ch === '(') depth++;
146
+ else if (ch === ')' && --depth === 0) return j + 1;
147
+ }
148
+ return -1;
149
+ };
150
+
151
+ /** A `$` or backtick at i. Returns the index after the expansion, or -1 when it never closes. */
152
+ const expansion = (i, inDouble) => {
153
+ const ch = command[i];
154
+ started = true;
155
+ if (ch === '`') {
156
+ for (let j = i + 1; j < n; j++) {
157
+ if (command[j] === '\\') j++;
158
+ else if (command[j] === '`') { dynamic = true; return j + 1; }
159
+ }
160
+ return -1;
161
+ }
162
+ const next = command[i + 1];
163
+ if (next === '(') { dynamic = true; return skipParens(i + 1); }
164
+ if (next === '{') {
165
+ const j = command.indexOf('}', i + 2);
166
+ dynamic = true;
167
+ return j < 0 ? -1 : j + 1;
168
+ }
169
+ if (!inDouble && next === "'") { // $'...' (ANSI-C quoting)
170
+ let j = i + 2;
171
+ let out = '';
172
+ for (; j < n && command[j] !== "'"; j++) {
173
+ if (command[j] === '\\' && j + 1 < n) {
174
+ j++;
175
+ out += ({ n: '\n', t: '\t', r: '\r' })[command[j]] ?? command[j];
176
+ } else out += command[j];
177
+ }
178
+ if (j >= n) return -1;
179
+ add(out);
180
+ return j + 1;
181
+ }
182
+ if (next !== undefined && /[A-Za-z0-9_@*#?!$-]/.test(next)) {
183
+ dynamic = true;
184
+ let j = i + 1;
185
+ while (j < n && /[A-Za-z0-9_]/.test(command[j])) j++;
186
+ return j === i + 1 ? i + 2 : j; // `$?`, `$$`, `$1`: one character
187
+ }
188
+ add('$'); // a lone `$` is just a dollar sign
189
+ return i + 1;
190
+ };
191
+
192
+ /** After an opening `"` at i - 1. Returns the index after the closing quote, or -1. */
193
+ const doubleQuoted = (i) => {
194
+ started = true;
195
+ const heredoc = HEREDOC_SUBSTITUTION.exec(command.slice(i));
196
+ if (heredoc && command[i + heredoc[0].length] === '"') {
197
+ const body = heredoc[1] === '-' ? heredoc[4].replace(/^\t+/gm, '') : heredoc[4];
198
+ add(body);
199
+ if (heredoc[2] === '' && /[$`]/.test(body)) dynamic = true;
200
+ return i + heredoc[0].length + 1;
201
+ }
202
+ while (i < n) {
203
+ const ch = command[i];
204
+ if (ch === '"') return i + 1;
205
+ if (ch === '\\') {
206
+ const next = command[i + 1];
207
+ if (next !== undefined && '$`"\\\n'.includes(next)) { if (next !== '\n') add(next); i += 2; }
208
+ else { add('\\'); i++; }
209
+ } else if (ch === '$' || ch === '`') {
210
+ i = expansion(i, true);
211
+ if (i < 0) return -1;
212
+ } else { add(ch); i++; }
213
+ }
214
+ return -1;
215
+ };
216
+
217
+ let i = 0;
218
+ while (i < n) {
219
+ const ch = command[i];
220
+ if (ch === ' ' || ch === '\t' || ch === '\r') { endWord(); i++; }
221
+ else if (ch === '\n' || ch === ';' || ch === '|') { endSegment(); i++; }
222
+ else if (ch === '&' && command[i + 1] === '&') { endSegment(); i += 2; }
223
+ else if (ch === '\\') {
224
+ if (command[i + 1] === '\n') i += 2; // line continuation
225
+ else if (i + 1 < n) { add(command[i + 1]); i += 2; }
226
+ else i++;
227
+ } else if (ch === "'") {
228
+ const j = command.indexOf("'", i + 1);
229
+ if (j < 0) return null;
230
+ add(command.slice(i + 1, j));
231
+ i = j + 1;
232
+ } else if (ch === '"') {
233
+ i = doubleQuoted(i + 1);
234
+ if (i < 0) return null;
235
+ } else if (ch === '$' || ch === '`') {
236
+ i = expansion(i, false);
237
+ if (i < 0) return null;
238
+ } else { add(ch); i++; }
239
+ }
240
+ endSegment();
241
+ return segments;
242
+ }
243
+
244
+ /** `git` options that take the next word as their value when written without `=`. */
245
+ const GIT_GLOBAL_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env', '--attr-source']);
246
+
247
+ /** Short `git commit` options whose value is the rest of the cluster, or the next word when the cluster ends there. */
248
+ const COMMIT_SHORT_WITH_VALUE = 'mFCct';
249
+ /** Short options that take an optional value only when attached (`-S<keyid>`, `-u<mode>`): the rest of the cluster. */
250
+ const COMMIT_SHORT_OPTIONAL_VALUE = 'Su';
251
+
252
+ /** Long `git commit` options that take a value (`--opt=v` or `--opt v`). */
253
+ const COMMIT_LONG_WITH_VALUE = new Set([
254
+ 'message', 'file', 'author', 'date', 'template', 'trailer', 'cleanup', 'reuse-message', 'reedit-message',
255
+ 'fixup', 'squash', 'pathspec-from-file', 'unified', 'inter-hunk-context',
256
+ ]);
257
+ /** The long `git commit` options without a value; with the above, the set git resolves unique abbreviations in. */
258
+ const COMMIT_LONG_FLAGS = [
259
+ 'all', 'patch', 'reset-author', 'short', 'branch', 'porcelain', 'long', 'null', 'signoff', 'no-signoff', 'verify',
260
+ 'no-verify', 'edit', 'no-edit', 'amend', 'post-rewrite', 'no-post-rewrite', 'include', 'only', 'interactive',
261
+ 'dry-run', 'status', 'no-status', 'untracked-files', 'verbose', 'no-verbose', 'quiet', 'gpg-sign', 'no-gpg-sign',
262
+ 'allow-empty', 'allow-empty-message', 'pathspec-file-nul',
263
+ ];
264
+ const COMMIT_LONG_ALL = [...COMMIT_LONG_WITH_VALUE, ...COMMIT_LONG_FLAGS];
265
+
266
+ /** git accepts any unambiguous prefix of a long option (`--mess=x` is `--message=x`). */
267
+ function resolveLong(name) {
268
+ if (COMMIT_LONG_ALL.includes(name)) return name;
269
+ const candidates = COMMIT_LONG_ALL.filter((o) => o.startsWith(name));
270
+ return candidates.length === 1 ? candidates[0] : name;
271
+ }
272
+
273
+ /**
274
+ * The message a single `git commit` word list carries on its command line, as git would assemble it, or null.
275
+ *
276
+ * Mirrors git's own option parsing: `-m` is found anywhere in a cluster of short flags (`-am`, `-vam`), its value is
277
+ * the rest of the cluster (`-mmsg`, `-m"msg"`) or the next word, `--message[=]` and its unambiguous abbreviations
278
+ * work too, and each `-m` is a paragraph of the message (joined by a blank line). Options that take a value
279
+ * (`--author x`, `-C HEAD`) are skipped as a pair so their value is not mistaken for anything else.
280
+ *
281
+ * null (nothing to judge) when:
282
+ * - there is no `-m` (`-F file`, `-C <commit>`, `--amend`, `--no-edit`, the editor): the text is not in the command;
283
+ * - `--fixup`/`--squash` is given: git writes its own `fixup! ...` subject and the `-m` text becomes the body;
284
+ * - the message is computed by the shell (`-m "$MSG"`, `$(...)`): its text is not known yet.
285
+ */
286
+ function messageOfCommit(args) {
287
+ const messages = [];
288
+ let judgeable = true;
289
+ const take = (word) => { messages.push(word.text); if (word.dynamic) judgeable = false; };
290
+
291
+ for (let i = 0; i < args.length; i++) {
292
+ const word = args[i].text;
293
+ if (word === '--') break; // what follows is a pathspec
294
+ if (word.startsWith('--')) {
295
+ const eq = word.indexOf('=');
296
+ const name = resolveLong(eq < 0 ? word.slice(2) : word.slice(2, eq));
297
+ if (name === 'fixup' || name === 'squash') judgeable = false;
298
+ if (!COMMIT_LONG_WITH_VALUE.has(name)) continue;
299
+ if (eq >= 0) {
300
+ if (name === 'message') take({ text: word.slice(eq + 1), dynamic: args[i].dynamic });
301
+ } else if (i + 1 < args.length) {
302
+ i++;
303
+ if (name === 'message') take(args[i]);
304
+ }
305
+ } else if (/^-[^-]/.test(word)) {
306
+ for (let k = 1; k < word.length; k++) {
307
+ const flag = word[k];
308
+ if (COMMIT_SHORT_OPTIONAL_VALUE.includes(flag)) break;
309
+ if (!COMMIT_SHORT_WITH_VALUE.includes(flag)) continue;
310
+ const rest = word.slice(k + 1);
311
+ let value = { text: rest, dynamic: args[i].dynamic };
312
+ if (rest === '' && i + 1 < args.length) value = args[++i];
313
+ else if (rest === '') break; // `-m` with nothing after it: git would fail
314
+ if (flag === 'm') take(value);
315
+ break;
316
+ }
317
+ }
318
+ }
319
+ return messages.length > 0 && judgeable ? messages.join('\n\n') : null;
320
+ }
321
+
322
+ /**
323
+ * The `git commit` word lists in a command line, one per commit: the command must BE a git commit, not merely
324
+ * mention one (`echo "git commit -m fake"` is an echo). Leading `VAR=value` words and git's global options
325
+ * (`git -C /tmp/repo commit`) may come before it.
326
+ */
327
+ function commitsIn(command) {
328
+ const segments = typeof command === 'string' ? tokenize(command) : null;
329
+ if (!segments) return [];
330
+ const commits = [];
331
+ for (const words of segments) {
332
+ let i = 0;
333
+ while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i].text)) i++;
334
+ if (words[i]?.text !== 'git') continue;
335
+ for (i++; i < words.length && words[i].text.startsWith('-'); i++) {
336
+ if (GIT_GLOBAL_WITH_VALUE.has(words[i].text)) i++;
337
+ }
338
+ if (words[i]?.text === 'commit') commits.push(words.slice(i + 1));
339
+ }
340
+ return commits;
341
+ }
342
+
343
+ /**
344
+ * Every commit message the command line itself carries, one per `git commit` in the command that has one to judge
345
+ * (`git add . && git commit -am "x" && git commit -m "y"` gives two). See messageOfCommit for what is left out.
346
+ *
347
+ * @param {unknown} command - the Bash tool command
348
+ * @returns {string[]}
349
+ */
350
+ export function commitMessagesFrom(command) {
351
+ return commitsIn(command).map(messageOfCommit).filter((m) => m !== null);
352
+ }
353
+
354
+ /**
355
+ * The message of the first `git commit` in the command that carries one, or null when there is nothing to judge.
356
+ * Kept for callers that want a single message; the hook itself judges all of them (commitMessagesFrom).
102
357
  */
103
358
  export function commitMessageFrom(command) {
104
- if (typeof command !== 'string') return null;
105
- const segment = command
106
- .split(/&&|\|\||[;|\n]/)
107
- .find((s) => /^\s*git\b/.test(s) && /\bcommit\b/.test(s));
108
- if (!segment) return null;
109
- const quoted = segment.match(/-m\s+(["'])([\s\S]*?)\1/);
110
- if (quoted) return quoted[2];
111
- const bare = segment.match(/-m\s+(\S+)/);
112
- return bare ? bare[1] : null; // -F, heredoc, or no -m: nothing to inspect
359
+ return commitMessagesFrom(command)[0] ?? null;
113
360
  }
114
361
 
115
362
  if (process.argv[1] && process.argv[1].endsWith('validate-commit-msg.mjs')) {
@@ -131,10 +378,9 @@ if (process.argv[1] && process.argv[1].endsWith('validate-commit-msg.mjs')) {
131
378
 
132
379
  if (payload && typeof payload === 'object') {
133
380
  // Claude Code PreToolUse. Silence unless this really is a commit.
134
- const msg = commitMessageFrom(payload?.tool_input?.command);
135
- if (msg === null) process.exit(0);
136
- if (validateCommitMessage(msg)) process.exit(0);
137
- complain(msg);
381
+ const bad = commitMessagesFrom(payload?.tool_input?.command).find((m) => !validateCommitMessage(m));
382
+ if (bad === undefined) process.exit(0);
383
+ complain(bad);
138
384
  process.exit(2); // 2 is what blocks a tool call
139
385
  }
140
386
 
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0
4
- translation_version: 6.14.0
5
- last_synced: 2026-10-22
6
- source_hash: 94f283a77794
3
+ source_version: 6.14.1-beta.1
4
+ translation_version: 6.14.1-beta.1
5
+ last_synced: 2026-10-30
6
+ source_hash: ba57d38f3b74
7
7
  status: current
8
8
  ---
9
9
 
@@ -18,6 +18,31 @@ status: current
18
18
 
19
19
  ## [Unreleased]
20
20
 
21
+ ## [6.14.1-beta.1] - 2026-10-30
22
+
23
+ > **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。**安全修正:** 危险指令 hook(`scripts/hooks/check-dangerous-cmd.mjs`)侦测到时以 exit 1 回报,而 Claude Code 不把 exit 1 当成拦截,因此 6.14.0 及更早版本从未挡下任何指令(重播 11,617 笔真实 shell 调用,规则命中 26 次,宿主挡下 0 次);现在改以 exit 2 结束,且只判断指令本身。**已经安装这个 hook 的项目会保留旧的脚本副本,直到你把它换掉;见“修复”的第一条。**另修正:提交信息 hook 略过 `git commit -am "..."` 与其他合并短旗标,以及 `uds update --skills --commands` 只运行两者其中之一。包含以下 6.14.0 的所有内容。
24
+
25
+ ### 新增
26
+
27
+ - **mock-boundary 1.3.0:能拦截的 hook 必须以宿主运行它的方式测试,并使用各宿主读取的信号。** UDS 自己的 `scripts/hooks/check-dangerous-cmd.mjs` 以 exit 1 结束,而 Claude Code 只在 exit 2 时拦截;它的测试导入比对函数,因此一直是绿的;重播 11,617 笔真实 shell 调用,规则命中 26 次,宿主挡下 0 次(已于 #281 修正)。标准现在规定:能挡下工具调用、提示或回合的 hook,必须(MUST)至少有一支测试把它当成进程启动,送入宿主自己的 stdin 数据,并断言宿主读取的结束码或 stdout JSON(H1);导入并调用内部函数的测试不计入,只断言「非 0」也不计入。同时应该(SHOULD)以同样方式运行一个放行案例(H2),并确认改掉挡下信号时测试会变红(H3)。标准附上一张表,列出 Claude Code、Codex、Gemini CLI 与 Antigravity CLI 在 PreToolUse 类事件中各自视为「已挡下」的信号,每一列都附官方出处,宿主页面没写的写「未查到」(Antigravity 的结束码行为没有文档,且其 stdin 使用 `toolCall` 而非 `tool_input`)。标准也注明:以同一份规则清单同时决定「该挡」与「不该挡」的真实调用重播,只证明接线,不证明规则(重播中 26 次命中全部与规则一致,0 次是真正的危险,而 `rm -fr /` 对它是隐形的)。`turn-completion-integrity` 1.5.1 仅在非 Stop 事件上指向新表;其 Stop 表与规则不变,信号只写在一处。对 UDS 自己出货的 hook 套用 H1 的 CI 闸门是 `npm run check:hook-entry-tests`。**谁会看到差异:** 采用者在下次 `uds update` 取得新文字;除非项目出货了拦截型 hook(此时标准要求多一支测试),否则项目内没有任何东西改变。同时更正 `mock-boundary.md` 的版本:同一份内容在 `mock-boundary.md` 写 1.1.0、在 `mock-boundary.ai.yaml` 写 1.2.0,现在两者都是 1.3.0。
28
+
29
+ ### 修复
30
+
31
+ - **危险指令 hook 现在会拦截,且不再挡下一般的清理指令。** `scripts/hooks/check-dangerous-cmd.mjs`(安全标准的 PreToolUse/Bash hook)从来没有挡下过任何东西:它以 exit 1 结束,而 Claude Code 只在 exit 2 时拦截工具调用,所以指令照常运行。它还拿整段 stdin JSON 来比对,而不是 `tool_input.command`。重播 11,617 笔真实 shell 调用,旧的 `rm -rf /` 规则命中 26 次,其中 25 次是无害的暂存清理(`rm -rf /tmp/x`),而 `rm -fr /` 与 `rm -r -f /` 却漏网。现在 hook 读取 `tool_input.command`(stdin 不是 JSON 时读取原始指令列),以 exit 2 拦截并在 stderr 写出规则名称;`rm` 只在递归且目标正好是 `/`、`/*`、`~`、`~/` 或 `$HOME` 时才拦截,旗标顺序不拘,`sudo` 之后也适用。原本从未命中任何东西的 fork bomb 规则(`()` 是空的 regex 群组)现在会命中;没有点号的 `mkfs`、没有 `if=` 的 `dd of=/dev/…`,以及对 `/` 之下路径的 `chmod -R 777`(以前会误中 `/home/me/x`)改以指令词判断,而不是子字符串。**行为改变:** `rm -rf /home` 与其他根目录之下的路径不再被拦截;它们不是这条规则原本要防的对象。命令行模式(`node check-dangerous-cmd.mjs "<command>"`)现在也以 exit 2 而非 1 结束。 **已经安装这个 hook 的项目不会从 `uds update` 获得修复:** 安装器会保留 `scripts/hooks/` 里已有的 hook 脚本;在这个版本上实测,`uds update --with-hooks`、`uds update --with-hooks --force` 与 `uds update --apply` 都让旧的 `check-dangerous-cmd.mjs` 原封不动(旧副本对 `rm -rf /` 仍以 exit 1 结束)。要获得修复,请把随附的文件复制过去覆盖:`cp "$(npm root -g)/universal-dev-standards/bundled/hooks/check-dangerous-cmd.mjs" scripts/hooks/`。在这个版本上运行 `uds init --with-hooks` 的项目会拿到修复后的脚本。
32
+ - **结构化日志 hook 现在会传到模型。** `scripts/hooks/check-logging-standard.mjs`(PostToolUse/Write)原本以 exit 1 结束,Claude Code 视为不拦截的 hook 错误,模型看不到消息;现在改以 exit 2,让 stderr 的建议回馈给模型,且只判断写入的文字(`tool_input.content` 或 `new_string`),不看 payload 的其余部分。Write 已经发生,所以这无法复原任何事。
33
+ - **提交信息 hook 现在检查 git 在命令行上接收消息的每一种写法,且不再挡下它误读的消息。** `scripts/hooks/validate-commit-msg.mjs`(PreToolUse/Bash hook)原本只在单独的 `-m` 之后找消息,所以 `git commit -am "wip"`(由它添加的进入点测试发现)与其他所有合并短旗标(`-vam`、`-sam`)都不经检查就放行。现在它像 git 一样读取命令:`-m` 出现在短旗标串的任何位置,值附在后面(`-m"msg"`、`-mmsg`、`-am"msg"`)或接在下一个词,`--message=msg`、`--message msg` 与 git 不含糊的缩写(`--mess=msg`),以及串接命令中的每一个 `git commit`(`git commit -m "feat: a" && git commit -m wip` 在第二个被挡下)。多个 `-m` 如 git 一样以空行相连,所以被判断的是第一个,即主旨。同一次重写也修掉两种误挡,成因是在读取引号之前就在 `;`、`&&`、`|` 与换行处切开命令:消息本身含其中之一(`-m "feat: a; b"`),以及 Claude Code 最常写的 `-m "$(cat <<'EOF' ... EOF)"` 形式——它以前被当成垃圾消息 `"$(cat` 挡下,现在改以本文判断。消息文字不在命令行上的提交照旧放行:`-F`、`-C`/`-c`、`--amend --no-edit`、编辑器、`--fixup`/`--squash`(git 自己写 `fixup!` 主旨,`-m` 变成本文),以及由 shell 计算的消息(`-m "$MSG"`、`$(...)`、反引号)。**行为改变:** 以前放行的命令,在消息不是 Conventional Commit 时现在会被挡下:`-am`/`-vam` 风格的提交、`--message`、串接命令的第二个提交,以及 `VAR=value` 之后的提交。
34
+ - **`uds update --skills --commands` 现在两者都更新;以前只更新一边,对另一边什么也没说(在 6.14.0 的 Windows 11 上发现)。** 两个旗标都带并加 `--apply` 时,只有指令运行:Skills 段落从未出现,manifest 里的 Skills 停在旧版本(一个项目:51 个指令已更新,Skills 仍在 6.11.0),结束码是 0。两个旗标都带但不加 `--apply` 时,只有 Skills 运行,`--commands` 被丢掉。旗标的顺序没有差别。原因:两个步骤各自在完成时结束整个进程,所以另一个永远没开始,且不加 `--apply` 的路径在第一个之后就返回。现在两者都运行,不论旗标顺序都是 Skills 先、指令后,各自印出自己的段落,并以两者中较差的结束码结束(任一边失败即非 0,`--apply` 对帐已记下的失败也一样)。单一范围(只带 `--skills` 或只带 `--commands`)的行为与输出和以前完全相同,`--plan --skills --commands` 本来就会规划两者,没有改变。**谁会看到差异:** 传过两个旗标的人。请再运行一次 `uds update --apply --yes --skills --commands`;经过那次有问题的运行的项目没有损坏,只是它的 Skills(或指令)落后。有一件事这次没有改变:只带单一范围的 `--apply` 在对帐中失败时仍以结束码 0 结束,因为该步骤一向以明确的 0 结束进程。
35
+
36
+ ### 变更
37
+
38
+ - **每个能拦截的 hook 现在都需要一支以宿主方式运行它的测试,并由 CI 强制运行(`npm run check:hook-entry-tests`)。** 新的 CI 工作 `scripts/check-hook-entry-tests.mjs` 从安装器推出 UDS 出货的 hook(各标准的 `enforcement:` 区块,加上 Codex、Gemini 与 Antigravity 的转接器),凡是能拦截的 hook,除非 `cli/tests` 下有测试真的启动该脚本、从 stdin 送入宿主格式的 payload 并断言 exit 2(Stop hook 则断言 stdout 的决定),否则失败。未分类的出货脚本同样失败。这是有已记载盲点的静态检查,附自我测试与样本测试。它抓到的第一个是没有进入点测试的 `validate-commit-msg.mjs`,现已补上一支。这就是上方 `mock-boundary` 1.3.0 规则所指的检查。它在 UDS 自己的 CI 中运行,不随 npm 套件出货。
39
+ - **正式版闸门现在也在发布时运行,且正式版必须等于它验收过的预发布版(XSPEC-498)。** 闸门原本只在 `scripts/bump-version.mjs` 里运行,所以从别处创建的 GitHub Release 会绕过它直接走到 `npm publish`;6.14.0 就是这样发出去的,比它验收过的预发布版(6.14.0-beta.15)多了四个修正与一次翻译同步。`publish.yml` 现在对正式版(预发布版不受影响)在 `npm publish` 之前运行 `scripts/beta-acceptance/check-stable-gate.mjs`,checkout 取得完整历史与 tag。闸门添加一条规则:HEAD 与预发布版 tag 的差异只能是版本档与发版纪录(三份更新日志、`docs/PRE-RELEASE.md`、验收报告);其他有变动的文件会使发布被拒绝并被列出,找不到 tag 或不是 git 保存库的文件夹同样被拒绝。版本档清单移到 `scripts/lib/version-files.mjs`,`bump-version.mjs` 现在由它写入,写入者与闸门共用同一份清单。**谁会看到差异:** 发布正式版的维护者;采用者与 CLI 用户看不到任何变化。
40
+ - **开发相依套件已更新,`npm audit` 高风险公告从 3 笔降为 0。** 只动 `cli/package-lock.json`(`npm audit fix`):`vite` 8.3.0 升到 8.3.5、`brace-expansion` 5.0.9 升到 5.0.12、`source-map-js` 1.2.1 升到 1.2.2,加上它们带进来的 `rolldown`、`postcss`、`nanoid` 升级;变动的每个套件都是开发相依,所以用户安装时不会拿到任何一项(#279)。6.14.0 之后的 Dependabot 更新是 `@commitlint/cli` 与 `@commitlint/config-conventional` 由 21.2.3 升到 21.2.4(根目录 `devDependencies`,#275、#276),以及 `/cli` 中 `lint-staged` 17.5.1 升到 17.6.0、`@vitest/coverage-v8` 5.0.3 升到 5.0.5、`@inquirer/prompts` 8.7.2 升到 8.7.4(#263、#261、#262)。这三项 `/cli` 更新只改了 `cli/package-lock.json`:`cli/package.json` 与 6.14.0 相同,所以用户安装时解析到的版本范围(`@inquirer/prompts` 是运行期相依,范围 `^8.7.2`)没有改变。
41
+
42
+ ### 测试
43
+
44
+ - **修正正式版闸门测试与语系安装测试在 Windows CI 上的时间上限。** `xspec-471-r5-stable-gate.test.js` 中会多次启动 `bump-version.mjs` 的八项测试,现在共用一个具名的 120 秒上限(其中四项曾在 `windows-latest` 上超过预设的 30 秒:#284 计入三项,#286 又补上一项);`init-every-declared-locale.test.js` 的每个语系安装现在各用一个以序号命名的文件夹,因为 `zh-cn` 与 `zh-CN` 在 Windows 与预设的 macOS 上是同一个文件夹,两个安装在里面互抢(准备阶段现在会拒绝忽略大小写后相同的名称,#280)。仅限测试;用户运行的东西没有任何改变。
45
+
21
46
  ## [6.14.0] - 2026-10-22
22
47
 
23
48
  > **正式版发布**:包含下方 6.14.0-beta.1 至 beta.15 的所有内容,加上本节列出的 beta.15 之后的修正。beta.15 已在 Windows、macOS、Linux 完成发布后验收(0 项失败)。
@@ -15,7 +15,7 @@ status: current
15
15
 
16
16
  > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
17
17
 
18
- **版本**: 6.14.0 | **发布日期**: 2026-10-22 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
18
+ **版本**: 6.14.1-beta.1 (Pre-release) | **发布日期**: 2026-10-30 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
19
19
 
20
20
  语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
21
21
 
@@ -14,6 +14,7 @@ status: current
14
14
  <!-- UDS_SUPPORTED_VERSIONS_START -->
15
15
  | 版本 | 支持状态 |
16
16
  |------|--------|
17
+ | 6.14.1-beta.1 | ✅ 预发布版本 |
17
18
  | 6.14.0 | ✅ 最新正式版 |
18
19
  | < 6.0.0 | ❌ 已终止支持 |
19
20
  <!-- UDS_SUPPORTED_VERSIONS_END -->
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/mock-boundary.md
3
- source_version: 1.1.0
4
- translation_version: 1.1.0
5
- last_synced: 2026-07-08
6
- source_hash: fe4715991a4c
3
+ source_version: 1.3.0
4
+ translation_version: 1.3.0
5
+ last_synced: 2026-10-28
6
+ source_hash: b95f3da59a8e
7
7
  status: current
8
8
  ---
9
9
 
@@ -11,8 +11,8 @@ status: current
11
11
 
12
12
  > **语言**: [English](../../../core/mock-boundary.md) | [繁體中文](../../zh-TW/core/mock-boundary.md) | 简体中文
13
13
 
14
- **版本**: 1.1.0
15
- **最后更新**: 2026-07-01
14
+ **版本**: 1.3.0
15
+ **最后更新**: 2026-10-28
16
16
  **适用性**: 所有具备单元测试与集成测试的软件项目
17
17
  **范围**: universal
18
18
  **行业标准**: ISTQB Foundation(Test Doubles), xUnit Patterns(Gerard Meszaros)
@@ -110,6 +110,67 @@ class DeterministicDispatcher implements BackgroundDispatcher {
110
110
 
111
111
  ---
112
112
 
113
+ ## 拦截型 Hook:测宿主的入口,不是测匹配函数
114
+
115
+ **hook** 是 AI 宿主(Claude Code、Codex、Gemini CLI、Antigravity CLI 等)在生命周期事件上运行的脚本。有些 hook 能**拦下**宿主原本要做的事:拒绝一次工具调用、拒绝一条提示、不让一个回合结束。对这类 hook,空心测试根本不需要任何 mock——测试只是从来没碰到宿主会调用的入口。
116
+
117
+ hook 有两层。**判断层**决定这条命令危不危险;**接线层**读宿主送来的 stdin 数据,并用宿主会读的信号回答(退出码,或标准输出的 JSON)。导入判断函数的单元测试只练到第一层,而宿主读的是第二层。退出码错、字段名称读错、输出格式宿主不认,这些都不会让那个测试变红。
118
+
119
+ ### 反例:UDS 自己的危险命令 hook,拦下 0/26
120
+
121
+ `scripts/hooks/check-dangerous-cmd.mjs` 是 PreToolUse hook。检测到危险命令时它 `exit 1`。Claude Code 只有 `exit 2` 才拦下工具调用;其他非 0 退出码都是不阻断的 hook 错误,命令照样执行。它的测试导入匹配函数(`isDangerousCommand()`)直接调用,所以绿了好几个月。
122
+
123
+ 重放 11,617 次真实 shell 调用(2026-10-27),规则 `rm -rf /` 命中 26 次,宿主拦下 **0** 次。26 次中有 25 次是无害的临时清理,例如 `rm -rf /tmp/x`;没有任何一次是真的要清空根目录。同一个规则还漏掉 `rm -fr /` 与 `rm -r -f /`。修正与入口测试在 PR #281 发布。
124
+
125
+ ### 规则
126
+
127
+ **H1(MUST)**:能拦下工具调用、提示或回合的 hook,至少要有一个测试同时做到下列三件事:
128
+
129
+ 1. **另起进程运行 hook**,用宿主配置文件里运行它的同一条命令。启动脚本算数;导入不算。
130
+ 2. **在 stdin 送入宿主自己的数据**,字段名称用该宿主的(见下表:Claude Code 送 `tool_name`/`tool_input`,Antigravity 送 `toolCall`)。照作者想象的宿主格式做出来的数据什么也证明不了。
131
+ 3. **断言宿主据以判断的信号**:确切的退出码,或宿主在标准输出解析的 JSON。“非 0”“有错误退出”“stderr 含某个词”都不算:exit 1 是非 0,却在 Claude Code 上什么也没拦。
132
+
133
+ 导入并调用内部函数的测试可以存在,对判断层也有用,但**不计入** H1。
134
+
135
+ **H2(SHOULD)**:拦下的用例旁边,用同样方式跑一个放行的用例,并断言宿主的放行信号(例如 exit 0 且标准输出为空)。一个什么都拦的 hook 可以通过只测拦下的测试。
136
+
137
+ **H3(SHOULD)**:切断检查——把 hook 的拦下信号改掉(例如 `exit 2` 改成 `exit 1`),确认入口测试变红。保持绿色,说明那个测试没在守接线。
138
+
139
+ H1 也适用于“唯一作用是让宿主读到它的信号”的 hook,例如用 exit 2 把 stderr 送到模型面前的 PostToolUse hook。工具已经跑完、无法撤销,但错的退出码一样会让这个 hook 无声无息。
140
+
141
+ ### 各宿主把什么当成“已拦下”
142
+
143
+ 2026-10-28 取自各宿主自己的官方文档。宿主会改这些约定;采信某一格之前请重查出处。格子写“未查到”,是读过该页而页面没写,不等于“没有”。
144
+
145
+ | 宿主 | 事件 | 拦下 | 不拦下 | 出处 |
146
+ |---|---|---|---|---|
147
+ | Claude Code | PreToolUse | exit **2**(stderr 是理由);或 exit 0 并在 stdout 输出 `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}` | 其他任何退出码,**包含 1**,都是不阻断的 hook 错误,动作照常进行;无效的 JSON 同理。文档写明的例外:配置了 `onFailure: "block"` 的 hook,失败时会拦下 | code.claude.com/docs/en/hooks:Exit code output、Exit code 2、Other exit codes、Decision control |
148
+ | Claude Code | UserPromptSubmit | exit **2**(提示不会送到模型);或 exit 0 并在 stdout 输出 `{"decision":"block","reason":"..."}` | 其他任何退出码(同样有 `onFailure: "block"` 的例外) | 同页,Exit code 2 behavior per event |
149
+ | Claude Code | PostToolUse | 不能拦:工具已经执行。exit 2 只会把 stderr 显示给模型 | 就拦下而言,任何退出码都不行 | 同页,Exit code 2 behavior per event |
150
+ | Codex | PreToolUse | exit **2** 并把理由写到 stderr;或 stdout 输出 `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}`;旧式 `{"decision":"block","reason":"..."}` 也接受 | stdout 的纯文本会被忽略;`permissionDecision:"ask"`、`continue:false`、`stopReason`、`suppressOutput` 尚不支持,该次 hook 运行被标为失败而工具调用继续;其他非 0 退出码:未查到 | developers.openai.com/codex/hooks,PreToolUse |
151
+ | Codex | UserPromptSubmit | exit **2** 并把理由写到 stderr;或 stdout 输出 `{"decision":"block","reason":"..."}` | stdout 纯文本会被当成额外上下文;其他非 0 退出码:未查到 | 同页,UserPromptSubmit |
152
+ | Codex | PermissionRequest | stdout 输出 `{"hookSpecificOutput":{"decision":{"behavior":"deny","message":"..."}}}`;任一 `deny` 即胜出 | 此事件的 exit 2:未查到;stdout 纯文本会被忽略 | 同页,PermissionRequest |
153
+ | Gemini CLI(旧版) | BeforeTool | exit **2**(stderr 是送给 agent 的理由);或 exit 0 并在 stdout 输出 `{"decision":"deny","reason":"..."}`(`"block"` 是别名)。文档把 JSON 形式列为优先路径 | 其他任何退出码只是警告,CLI 继续 | geminicli.com/docs/hooks/reference,Global hook mechanics 与 BeforeTool |
154
+ | Gemini CLI(旧版) | BeforeAgent、BeforeModel | exit **2** 中止该回合(BeforeAgent 还会把提示从上下文抹除;BeforeModel 跳过 LLM 调用);或 `decision:"deny"` | 同上 | 同页 |
155
+ | Antigravity CLI(`agy`) | PreToolUse | exit 0 并在 stdout 输出 `{"decision":"deny","reason":"..."}`(“Hard blocks execution immediately”)。`decision` 字段必填,其他值为 `allow`、`auto_approve`、`ask`、`force_ask`、`deny_unless_prior_grant`。stdin 带的是 `toolCall.name` 与 `toolCall.args`,不是 Claude Code 的字段名 | 退出码语义:未查到(官方页面没写)。不要假设 Claude Code 的 exit 2 适用。第三方文章声称任何非 0 都视为拒绝;那不是官方说法,此处不采用 | antigravity.google/docs/hooks,Input and output contract,PreToolUse |
156
+ | Cursor 与其他宿主 | 任何 | 未查到(本版未调查) | 未查到 | 无 |
157
+
158
+ Stop 类事件(Claude Code 与 Codex 的 Stop、Gemini CLI 的 AfterAgent、Antigravity 的 Stop)**不在这里重复**。它们的拦下约定写在 [turn-completion-integrity](turn-completion-integrity.md) 的“支持的执行环境”表,那是唯一写下它们的地方。该表也记录了一个 Antigravity hook 失败后被静默放行的案例,与本节要防的接线失败是同一类。
159
+
160
+ ### 重放验证的是接线,不是规则
161
+
162
+ 把录下的真实调用重放给 hook(例如用 rules-to-guards)是检查接线的有力方法。但它有一个每次汇报结果时都必须讲明的限制:若同一份规则清单同时决定“该拦”与“不该拦”,重放只证明 hook 照它的规则运行,**不证明规则本身是对的**。
163
+
164
+ 0/26 之所以量得出来,是因为宿主的约定(exit 2 才拦)是 hook 之外的事实。至于“哪些命令值得拦”,手上只有 hook 自己的匹配式:26 次命中都与它一致,真正的危险 0 次,而它没覆盖的 `rm -fr /` 永远不会在重放里显示为漏掉,因为答案来源与 hook 共用同一个盲点。
165
+
166
+ 所以重放的结果只能报“接线正确”或“接线错误”,不要由它得出“规则正确”。要对规则下结论,请去读实际命中的命令,或另备一份不看 hook 匹配式写成的独立答案(见 [verification-oracle](../../../core/verification-oracle.md))。
167
+
168
+ ### UDS 的执行方式
169
+
170
+ UDS 在 CI 对自己发布的 hook 检查这条规则:`node scripts/check-hook-entry-tests.mjs`(npm 命令 `check:hook-entry-tests`),发布的、能拦下的 hook 若没有“启动它、送 stdin、断言宿主信号”的测试就判失败。它是静态文本分析:只证明“形状对的测试存在”,不证明 hook 退化时那个测试会变红——那是 H3 的工作。
171
+
172
+ ---
173
+
113
174
  ## 空心测试检测
114
175
 
115
176
  提交测试文件之前,请检查:
@@ -118,6 +179,7 @@ class DeterministicDispatcher implements BackgroundDispatcher {
118
179
  2. **所有断言都是 `.toHaveBeenCalled()` 系列** → 加入输出值断言
119
180
  3. **Mock 路径与被测对象目录相同** → 自我引用 mock;移除之
120
181
  4. **Mock 设置行数多于断言行数** → 很可能是空心测试
182
+ 5. **拦截型 hook 的测试只导入并调用它的函数** → 补一个启动 hook 并断言宿主信号的入口测试(见“拦截型 Hook”)
121
183
 
122
184
  ---
123
185
 
@@ -128,6 +190,7 @@ class DeterministicDispatcher implements BackgroundDispatcher {
128
190
  - **Orphan Mock**:跨模块 mock 却没有对应的集成测试
129
191
  - **Security Bypass Mock**:auth/权限逻辑被换成直接放行的 stub
130
192
  - **Database Mock Cascade**:DB 返回硬编码的数据,隐藏真实查询错误
193
+ - **Matcher-Only Hook Test**:拦截型 hook 的测试只导入并调用其判断函数,从未按宿主的方式运行 hook。hook 什么也没拦,测试却是绿的(UDS 自己的 0/26)
131
194
  - **Poll/Sleep for Background Result**:用 sleep 或 poll 等待 fire-and-forget 后台工作完成。race 依然存在——timeout 只是多数时候把它掩盖住,同时拖慢整个测试套件;在共享 runner 上还会把 flakiness 泄漏到其他 MR 的 CI 中。应改为注入 deterministic runner 并 await 被追踪的 task。
132
195
 
133
196
  ---
@@ -142,6 +205,8 @@ class DeterministicDispatcher implements BackgroundDispatcher {
142
205
  | 禁止 mock 安全机制 | 测试涉及 auth/权限 | 使用真实测试用户 + 真实 token |
143
206
  | 空心评审 | Mock 数量 ≥ import 数量 | 加入输出值断言 |
144
207
  | 后台工作禁止 poll/sleep | 测试断言某个 fire-and-forget 副作用 | 注入 deterministic runner;await 被追踪的 task |
208
+ | 拦截型 hook 要有宿主入口测试 | hook 能拦下工具调用、提示或回合 | 启动它、在 stdin 送宿主的数据、断言宿主据以判断的退出码或 stdout JSON |
209
+ | 重放只证明接线 | 汇报把真实调用重放给 hook 的结果 | 报“接线正确”;除非规则另以独立答案核对过,否则不报“规则正确” |
145
210
 
146
211
  ---
147
212
 
@@ -150,6 +215,8 @@ class DeterministicDispatcher implements BackgroundDispatcher {
150
215
  - **testing**:Mock 边界规则适用于测试金字塔的所有测试级别
151
216
  - **test-completeness-dimensions**:维度 8(AI 测试质量)引用了这些规则
152
217
  - **flow-based-testing**:Flow 测试必须遵循 mock 边界规则
218
+ - **turn-completion-integrity**:Stop 类事件的拦下约定写在那里;工具与提示事件的写在本标准,两边都不重复对方
219
+ - **verification-oracle**:用来判断 hook 规则对不对的答案来源,不得由 hook 自己的匹配式推出
153
220
 
154
221
  ---
155
222
 
@@ -159,3 +226,4 @@ class DeterministicDispatcher implements BackgroundDispatcher {
159
226
  |------|------|------|
160
227
  | 1.0.0 | 2026-05-04 | 初始标准:空心测试问题、可/不可 Mock 表格、检测、反模式、规则摘要 |
161
228
  | 1.1.0 | 2026-07-01 | 新增可注入的后台执行作为 seam(平行于 clock injection):可 Mock 表格新增行、`可注入的后台执行` 章节、`Poll/Sleep for Background Result` 反模式,以及后台工作禁止 poll/sleep 规则(issue #143) |
229
+ | 1.3.0 | 2026-10-28 | 新增《拦截型 Hook:测宿主的入口,不是测匹配函数》:H1 MUST(启动 hook、送宿主的 stdin 数据、断言宿主据以判断的信号)、H2/H3 SHOULD、各宿主拦下信号对照表,以及“重放验证接线、不验证规则”的注记,并以 UDS 自己的 0/26 为反例。版本号与 `mock-boundary.ai.yaml` 对齐——该文件先前把“后台执行”那次新增记为 1.2.0,本文件记为 1.1.0 |
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/turn-completion-integrity.md
3
- source_version: 1.5.0
4
- translation_version: 1.5.0
5
- last_synced: 2026-09-29
6
- source_hash: 08579653d9a4
3
+ source_version: 1.5.1
4
+ translation_version: 1.5.1
5
+ last_synced: 2026-10-28
6
+ source_hash: 46c790f970d3
7
7
  status: current
8
8
  ---
9
9
 
@@ -11,8 +11,8 @@ status: current
11
11
 
12
12
  > **语言**: [English](../../../core/turn-completion-integrity.md) | [繁體中文](../../zh-TW/core/turn-completion-integrity.md) | 简体中文
13
13
 
14
- **版本**: 1.5.0
15
- **最后更新**: 2026-09-29
14
+ **版本**: 1.5.1
15
+ **最后更新**: 2026-10-28
16
16
  **适用范围**: 任何由 agent 结束回合、把控制权交还给人的执行环境
17
17
  **Scope**: universal
18
18
  **行业标准**: 不声称任何来源——由实际观察到的失败归纳,见「证据」
@@ -153,6 +153,8 @@ agent 写下「我接着做 X」,然后结束回合,而 X 没有做。
153
153
  | Gemini CLI(过时) | AfterAgent | `.gemini/settings.json` | stdout 输出 `{"decision":"deny","reason":...}`,exit 0——官方文档标记为优先于 exit code 2 的做法 |
154
154
  | Antigravity CLI(`agy`) | Stop | `.agents/hooks.json` | stdout 输出 `{"decision":"continue","reason":...}`,exit 0;`{}` 即放行 |
155
155
 
156
+ 这张表只涵盖 Stop 类事件。宿主对“拦下工具调用或提示”的事件(PreToolUse、UserPromptSubmit、BeforeTool)所读的信号,写在 [mock-boundary](mock-boundary.md) 的“各宿主把什么当成“已拦下””表——那是唯一写下它们的地方,连同“拦截型 hook 必须按宿主的方式运行来测”的规则,本处不重复。
157
+
156
158
  在 Codex 上,接上了不等于会执行。Codex 会跳过项目级的 hook,直到项目被信任、**而且**
157
159
  这一支 hook 的定义在交互式 Codex 会话里通过 `/hooks` 被信任为止;信任记录绑定在定义的
158
160
  哈希值上,定义一改就要重新信任。在 `codex exec` 下,未被信任的 hook 会被跳过,而且完全
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0
4
- translation_version: 6.14.0
5
- last_synced: 2026-10-22
6
- source_hash: 94f283a77794
3
+ source_version: 6.14.1-beta.1
4
+ translation_version: 6.14.1-beta.1
5
+ last_synced: 2026-10-30
6
+ source_hash: ba57d38f3b74
7
7
  status: current
8
8
  ---
9
9
 
@@ -18,6 +18,31 @@ status: current
18
18
 
19
19
  ## [Unreleased]
20
20
 
21
+ ## [6.14.1-beta.1] - 2026-10-30
22
+
23
+ > **測試版**——以 `npm install -g universal-dev-standards@beta` 安裝。要測什麼、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。**安全修正:** 危險指令 hook(`scripts/hooks/check-dangerous-cmd.mjs`)偵測到時以 exit 1 回報,而 Claude Code 不把 exit 1 當成攔截,因此 6.14.0 及更早版本從未擋下任何指令(重播 11,617 筆真實 shell 呼叫,規則命中 26 次,宿主擋下 0 次);現在改以 exit 2 結束,且只判斷指令本身。**已經安裝這個 hook 的專案會保留舊的腳本副本,直到你把它換掉;見「修正」的第一條。**另修正:提交訊息 hook 略過 `git commit -am "..."` 與其他合併短旗標,以及 `uds update --skills --commands` 只執行兩者其中之一。包含以下 6.14.0 的所有內容。
24
+
25
+ ### 新增
26
+
27
+ - **mock-boundary 1.3.0:能攔截的 hook 必須以宿主執行它的方式測試,並使用各宿主讀取的訊號。** UDS 自己的 `scripts/hooks/check-dangerous-cmd.mjs` 以 exit 1 結束,而 Claude Code 只在 exit 2 時攔截;它的測試匯入比對函式,因此一直是綠的;重播 11,617 筆真實 shell 呼叫,規則命中 26 次,宿主擋下 0 次(已於 #281 修正)。標準現在規定:能擋下工具呼叫、提示或回合的 hook,必須(MUST)至少有一支測試把它當成行程啟動,送入宿主自己的 stdin 資料,並斷言宿主讀取的結束碼或 stdout JSON(H1);匯入並呼叫內部函式的測試不計入,只斷言「非 0」也不計入。同時應該(SHOULD)以同樣方式執行一個放行案例(H2),並確認改掉擋下訊號時測試會變紅(H3)。標準附上一張表,列出 Claude Code、Codex、Gemini CLI 與 Antigravity CLI 在 PreToolUse 類事件中各自視為「已擋下」的訊號,每一列都附官方出處,宿主頁面沒寫的寫「未查到」(Antigravity 的結束碼行為沒有文件,且其 stdin 使用 `toolCall` 而非 `tool_input`)。標準也註明:以同一份規則清單同時決定「該擋」與「不該擋」的真實呼叫重播,只證明接線,不證明規則(重播中 26 次命中全部與規則一致,0 次是真正的危險,而 `rm -fr /` 對它是隱形的)。`turn-completion-integrity` 1.5.1 僅在非 Stop 事件上指向新表;其 Stop 表與規則不變,訊號只寫在一處。對 UDS 自己出貨的 hook 套用 H1 的 CI 閘門是 `npm run check:hook-entry-tests`。**誰會看到差異:** 採用者在下次 `uds update` 取得新文字;除非專案出貨了攔截型 hook(此時標準要求多一支測試),否則專案內沒有任何東西改變。同時更正 `mock-boundary.md` 的版本:同一份內容在 `mock-boundary.md` 寫 1.1.0、在 `mock-boundary.ai.yaml` 寫 1.2.0,現在兩者都是 1.3.0。
28
+
29
+ ### 修正
30
+
31
+ - **危險指令 hook 現在會攔截,且不再擋下一般的清理指令。** `scripts/hooks/check-dangerous-cmd.mjs`(安全標準的 PreToolUse/Bash hook)從來沒有擋下過任何東西:它以 exit 1 結束,而 Claude Code 只在 exit 2 時攔截工具呼叫,所以指令照常執行。它還拿整段 stdin JSON 來比對,而不是 `tool_input.command`。重播 11,617 筆真實 shell 呼叫,舊的 `rm -rf /` 規則命中 26 次,其中 25 次是無害的暫存清理(`rm -rf /tmp/x`),而 `rm -fr /` 與 `rm -r -f /` 卻漏網。現在 hook 讀取 `tool_input.command`(stdin 不是 JSON 時讀取原始指令列),以 exit 2 攔截並在 stderr 寫出規則名稱;`rm` 只在遞迴且目標正好是 `/`、`/*`、`~`、`~/` 或 `$HOME` 時才攔截,旗標順序不拘,`sudo` 之後也適用。原本從未命中任何東西的 fork bomb 規則(`()` 是空的 regex 群組)現在會命中;沒有點號的 `mkfs`、沒有 `if=` 的 `dd of=/dev/…`,以及對 `/` 之下路徑的 `chmod -R 777`(以前會誤中 `/home/me/x`)改以指令詞判斷,而不是子字串。**行為改變:** `rm -rf /home` 與其他根目錄之下的路徑不再被攔截;它們不是這條規則原本要防的對象。命令列模式(`node check-dangerous-cmd.mjs "<command>"`)現在也以 exit 2 而非 1 結束。 **已經安裝這個 hook 的專案不會從 `uds update` 取得修正:** 安裝器會保留 `scripts/hooks/` 裡已有的 hook 腳本;在這個版本上實測,`uds update --with-hooks`、`uds update --with-hooks --force` 與 `uds update --apply` 都讓舊的 `check-dangerous-cmd.mjs` 原封不動(舊副本對 `rm -rf /` 仍以 exit 1 結束)。要取得修正,請把隨附的檔案複製過去覆蓋:`cp "$(npm root -g)/universal-dev-standards/bundled/hooks/check-dangerous-cmd.mjs" scripts/hooks/`。在這個版本上執行 `uds init --with-hooks` 的專案會拿到修正後的腳本。
32
+ - **結構化日誌 hook 現在會傳到模型。** `scripts/hooks/check-logging-standard.mjs`(PostToolUse/Write)原本以 exit 1 結束,Claude Code 視為不攔截的 hook 錯誤,模型看不到訊息;現在改以 exit 2,讓 stderr 的建議回饋給模型,且只判斷寫入的文字(`tool_input.content` 或 `new_string`),不看 payload 的其餘部分。Write 已經發生,所以這無法復原任何事。
33
+ - **提交訊息 hook 現在檢查 git 在命令列上接收訊息的每一種寫法,且不再擋下它誤讀的訊息。** `scripts/hooks/validate-commit-msg.mjs`(PreToolUse/Bash hook)原本只在單獨的 `-m` 之後找訊息,所以 `git commit -am "wip"`(由它新增的進入點測試發現)與其他所有合併短旗標(`-vam`、`-sam`)都不經檢查就放行。現在它像 git 一樣讀取命令:`-m` 出現在短旗標串的任何位置,值附在後面(`-m"msg"`、`-mmsg`、`-am"msg"`)或接在下一個詞,`--message=msg`、`--message msg` 與 git 不含糊的縮寫(`--mess=msg`),以及串接命令中的每一個 `git commit`(`git commit -m "feat: a" && git commit -m wip` 在第二個被擋下)。多個 `-m` 如 git 一樣以空行相連,所以被判斷的是第一個,即主旨。同一次重寫也修掉兩種誤擋,成因是在讀取引號之前就在 `;`、`&&`、`|` 與換行處切開命令:訊息本身含其中之一(`-m "feat: a; b"`),以及 Claude Code 最常寫的 `-m "$(cat <<'EOF' ... EOF)"` 形式——它以前被當成垃圾訊息 `"$(cat` 擋下,現在改以本文判斷。訊息文字不在命令列上的提交照舊放行:`-F`、`-C`/`-c`、`--amend --no-edit`、編輯器、`--fixup`/`--squash`(git 自己寫 `fixup!` 主旨,`-m` 變成本文),以及由 shell 計算的訊息(`-m "$MSG"`、`$(...)`、反引號)。**行為改變:** 以前放行的命令,在訊息不是 Conventional Commit 時現在會被擋下:`-am`/`-vam` 風格的提交、`--message`、串接命令的第二個提交,以及 `VAR=value` 之後的提交。
34
+ - **`uds update --skills --commands` 現在兩者都更新;以前只更新一邊,對另一邊什麼也沒說(在 6.14.0 的 Windows 11 上發現)。** 兩個旗標都帶並加 `--apply` 時,只有指令執行:Skills 段落從未出現,manifest 裡的 Skills 停在舊版本(一個專案:51 個指令已更新,Skills 仍在 6.11.0),結束碼是 0。兩個旗標都帶但不加 `--apply` 時,只有 Skills 執行,`--commands` 被丟掉。旗標的順序沒有差別。原因:兩個步驟各自在完成時結束整個程序,所以另一個永遠沒開始,且不加 `--apply` 的路徑在第一個之後就返回。現在兩者都執行,不論旗標順序都是 Skills 先、指令後,各自印出自己的段落,並以兩者中較差的結束碼結束(任一邊失敗即非 0,`--apply` 對帳已記下的失敗也一樣)。單一範圍(只帶 `--skills` 或只帶 `--commands`)的行為與輸出和以前完全相同,`--plan --skills --commands` 本來就會規劃兩者,沒有改變。**誰會看到差異:** 傳過兩個旗標的人。請再執行一次 `uds update --apply --yes --skills --commands`;經過那次有問題的執行的專案沒有損壞,只是它的 Skills(或指令)落後。有一件事這次沒有改變:只帶單一範圍的 `--apply` 在對帳中失敗時仍以結束碼 0 結束,因為該步驟一向以明確的 0 結束程序。
35
+
36
+ ### 變更
37
+
38
+ - **每個能攔截的 hook 現在都需要一支以宿主方式執行它的測試,並由 CI 強制執行(`npm run check:hook-entry-tests`)。** 新的 CI 工作 `scripts/check-hook-entry-tests.mjs` 從安裝器推出 UDS 出貨的 hook(各標準的 `enforcement:` 區塊,加上 Codex、Gemini 與 Antigravity 的轉接器),凡是能攔截的 hook,除非 `cli/tests` 下有測試真的啟動該腳本、從 stdin 送入宿主格式的 payload 並斷言 exit 2(Stop hook 則斷言 stdout 的決定),否則失敗。未分類的出貨腳本同樣失敗。這是有已記載盲點的靜態檢查,附自我測試與樣本測試。它抓到的第一個是沒有進入點測試的 `validate-commit-msg.mjs`,現已補上一支。這就是上方 `mock-boundary` 1.3.0 規則所指的檢查。它在 UDS 自己的 CI 中執行,不隨 npm 套件出貨。
39
+ - **正式版閘門現在也在發布時執行,且正式版必須等於它驗收過的預覽版(XSPEC-498)。** 閘門原本只在 `scripts/bump-version.mjs` 裡執行,所以從別處建立的 GitHub Release 會繞過它直接走到 `npm publish`;6.14.0 就是這樣發出去的,比它驗收過的預覽版(6.14.0-beta.15)多了四個修正與一次翻譯同步。`publish.yml` 現在對正式版(預覽版不受影響)在 `npm publish` 之前執行 `scripts/beta-acceptance/check-stable-gate.mjs`,checkout 取得完整歷史與 tag。閘門新增一條規則:HEAD 與預覽版 tag 的差異只能是版本檔與發版紀錄(三份更新日誌、`docs/PRE-RELEASE.md`、驗收報告);其他有變動的檔案會使發布被拒絕並被列出,找不到 tag 或不是 git 儲存庫的資料夾同樣被拒絕。版本檔清單移到 `scripts/lib/version-files.mjs`,`bump-version.mjs` 現在由它寫入,寫入者與閘門共用同一份清單。**誰會看到差異:** 發布正式版的維護者;採用者與 CLI 使用者看不到任何變化。
40
+ - **開發相依套件已更新,`npm audit` 高風險公告從 3 筆降為 0。** 只動 `cli/package-lock.json`(`npm audit fix`):`vite` 8.3.0 升到 8.3.5、`brace-expansion` 5.0.9 升到 5.0.12、`source-map-js` 1.2.1 升到 1.2.2,加上它們帶進來的 `rolldown`、`postcss`、`nanoid` 升級;變動的每個套件都是開發相依,所以使用者安裝時不會拿到任何一項(#279)。6.14.0 之後的 Dependabot 更新是 `@commitlint/cli` 與 `@commitlint/config-conventional` 由 21.2.3 升到 21.2.4(根目錄 `devDependencies`,#275、#276),以及 `/cli` 中 `lint-staged` 17.5.1 升到 17.6.0、`@vitest/coverage-v8` 5.0.3 升到 5.0.5、`@inquirer/prompts` 8.7.2 升到 8.7.4(#263、#261、#262)。這三項 `/cli` 更新只改了 `cli/package-lock.json`:`cli/package.json` 與 6.14.0 相同,所以使用者安裝時解析到的版本範圍(`@inquirer/prompts` 是執行期相依,範圍 `^8.7.2`)沒有改變。
41
+
42
+ ### 測試
43
+
44
+ - **修正正式版閘門測試與語系安裝測試在 Windows CI 上的時間上限。** `xspec-471-r5-stable-gate.test.js` 中會多次啟動 `bump-version.mjs` 的八項測試,現在共用一個具名的 120 秒上限(其中四項曾在 `windows-latest` 上超過預設的 30 秒:#284 計入三項,#286 又補上一項);`init-every-declared-locale.test.js` 的每個語系安裝現在各用一個以序號命名的資料夾,因為 `zh-cn` 與 `zh-CN` 在 Windows 與預設的 macOS 上是同一個資料夾,兩個安裝在裡面互搶(準備階段現在會拒絕忽略大小寫後相同的名稱,#280)。僅限測試;使用者執行的東西沒有任何改變。
45
+
21
46
  ## [6.14.0] - 2026-10-22
22
47
 
23
48
  > **正式版發布**:包含下方 6.14.0-beta.1 至 beta.15 的所有內容,加上本節列出的 beta.15 之後的修正。beta.15 已在 Windows、macOS、Linux 完成發布後驗收(0 項失敗)。
@@ -15,7 +15,7 @@ status: current
15
15
 
16
16
  > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
17
17
 
18
- **版本**: 6.14.0 | **發布日期**: 2026-10-22 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
18
+ **版本**: 6.14.1-beta.1 (Pre-release) | **發布日期**: 2026-10-30 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
19
19
 
20
20
  語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
21
21