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

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.2
4
+ translation_version: 6.14.1-beta.2
5
+ last_synced: 2026-10-29
6
+ source_hash: 5dcc2a09effc
7
7
  status: current
8
8
  ---
9
9
 
@@ -18,6 +18,43 @@ status: current
18
18
 
19
19
  ## [Unreleased]
20
20
 
21
+ ## [6.14.1-beta.2] - 2026-10-30
22
+
23
+ > **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。**在 6.14.1-beta.1 之上的一项修复:** `uds update --with-hooks` 现在会替换旧版 UDS 安装、且没有人改过的 hook 脚本,即使 hook 已经配置好。因此已有危险指令 hook 的项目会拿到会拦截的版本;beta.1 留下的是从不拦截的旧副本,还得你手动复制文件。包含以下 6.14.1-beta.1 的所有内容。
24
+
25
+ ### 修复
26
+
27
+ - **`uds update --with-hooks` 现在会替换旧版 UDS 安装、且没有人改过的 hook 脚本,即使 hook 已经配置好。** 在 6.14.1-beta.1,已经有危险指令 hook 的项目会留着 6.14.0 的 `scripts/hooks/check-dangerous-cmd.mjs`,它以 exit 1 结束、从不拦截:安装器看到 hook 配置“已存在”,打印“已安装、未动”,从不比对旁边的脚本(实测:`uds update --with-hooks`、`uds update --with-hooks --force` 与 `uds update --apply` 都让它原封不动)。现在不论配置是否已存在,每个工具都会比对。与出货版不同的脚本按内容判断:若与历代 UDS 某版出货的内容逐字节相同(忽略换行符,所以 Windows 在 `core.autocrlf` 下的检出仍算),说明没人改过,直接替换,输出会列出每个文件及它来自哪一版;其他任何差异都说明被改过:保留、列出,并说明如何强制。历代内容列在 `cli/src/installers/hook-script-fingerprints.json`,由 `scripts/generate-hook-fingerprints.mjs` 从 git 标签生成(不是手写,也不会被缩减);单元测试在 `scripts/hooks/` 任一脚本的内容不在清单里时失败,所以改了 hook 就无法不更新清单而提交,`scripts/pre-release-check.sh` 的第 29 步另检查每个发版标签。报告依“实际写入”而非“测量结果”。**`--force`:** 搭配 `--with-hooks` 时,现在连被改过的 hook 脚本也会用出货版覆盖,hook 已经安装时也一样(以前只在补装缺少的 hook 时才会),输出会说覆盖了几个;你的修改没有备份。`--with-hooks --plan` 列出将替换或覆盖的项目,且不写任何文件。**`--apply`、单独的 `--force` 与普通的 `uds update` 不管理 hook 脚本,仍然不会替换它们;**当其中一个是过期且未改过的副本时,它们现在会打印一行说明,并指出 `uds update --with-hooks`。**谁会看到差异:** 用 6.14.0 或更早版本安装过 hook、并在这个版本运行 `uds update --with-hooks` 的人:他们没改过的每个 hook 脚本都会被替换(替换的文件有记录,所以 `uds uninstall` 仍会移除)。**如果你改过 hook 脚本**,它会被保留,在你手动合并或使用 `--force` 之前拿不到之后的修复(以危险指令 hook 来说,就是 exit 2 的修复)。
28
+
29
+ ### 测试
30
+
31
+ - **macOS 发布后验收不再丢失步骤输出的结尾(在 6.14.0 与 6.14.1-beta.1 发现)。** `xspec482-init-interactive-manual` 只在 macOS 上红:捕获到的输出在一行中间断掉,没有驱动程序最后打印的 `DRIVE-EXIT=0`,但 `uds init` 其实成功了。`scripts/beta-acceptance/steps.json` 里的验收辅助程序(两个交互式驱动程序与三个小包装)在写出结果后立刻调用 `process.exit()`。标准输出是管道时,Node 在 macOS 上把放不进管道的部分异步写出,`process.exit()` 会把剩下的丢掉;Linux 上同样的写入是同步的,所以同一步在那里是绿的。现在它们等写完才结束(写入的回调,或 `process.exitCode`)。验证:新增一个测试,用真正的驱动程序文本对一个打印 300 KB 的替身、搭配读得很慢的读取端;在 macOS 上,修改前只收到 65,536 字节、没有 `DRIVE-EXIT` 行,修改后收到全部输出。**没有证明的部分:** 真实步骤只打印约 2.8 KB,放得进管道,而且在维护者的 macOS 上修改前后都通过,所以 CI 上输出丢失出自这个原因是合理的判断,不是测到的结果;以本版的发布后验收为准。仅改动测试与验收程序;用户运行的东西没有变。
32
+
33
+ ## [6.14.1-beta.1] - 2026-10-30
34
+
35
+ > **测试版**——以 `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 的项目会保留旧的脚本副本,直到你手动换掉;6.14.1-beta.2(见上)已修复:`uds update --with-hooks` 会替换它。**另修正:提交信息 hook 略过 `git commit -am "..."` 与其他合并短旗标,以及 `uds update --skills --commands` 只运行两者其中之一。包含以下 6.14.0 的所有内容。
36
+
37
+ ### 新增
38
+
39
+ - **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。
40
+
41
+ ### 修复
42
+
43
+ - **危险指令 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 结束),当时的解法是手动把随附的文件复制过去覆盖。6.14.1-beta.2(见上)已修复这一点。在这个版本上运行 `uds init --with-hooks` 的项目拿到的是修复后的脚本。
44
+ - **结构化日志 hook 现在会传到模型。** `scripts/hooks/check-logging-standard.mjs`(PostToolUse/Write)原本以 exit 1 结束,Claude Code 视为不拦截的 hook 错误,模型看不到消息;现在改以 exit 2,让 stderr 的建议回馈给模型,且只判断写入的文字(`tool_input.content` 或 `new_string`),不看 payload 的其余部分。Write 已经发生,所以这无法复原任何事。
45
+ - **提交信息 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` 之后的提交。
46
+ - **`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 结束进程。
47
+
48
+ ### 变更
49
+
50
+ - **每个能拦截的 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 套件出货。
51
+ - **正式版闸门现在也在发布时运行,且正式版必须等于它验收过的预发布版(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 用户看不到任何变化。
52
+ - **开发相依套件已更新,`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`)没有改变。
53
+
54
+ ### 测试
55
+
56
+ - **修正正式版闸门测试与语系安装测试在 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)。仅限测试;用户运行的东西没有任何改变。
57
+
21
58
  ## [6.14.0] - 2026-10-22
22
59
 
23
60
  > **正式版发布**:包含下方 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.2 (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.2 | ✅ 预发布版本 |
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,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-10-13
3
+ > Quick reference for all UDS features | Last updated: 2026-10-30
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
6
6
 
@@ -356,6 +356,7 @@
356
356
  | `check-error-exit.mjs` | 🔴 沒填就是沒設定,而沒設定會 exit 2, |
357
357
  | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ- |
358
358
  | `check-home-untouched.mjs` | check-home-untouched — did this run write anywhere |
359
+ | `check-hook-entry-tests.mjs` | / |
359
360
  | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 to |
360
361
  | `check-orphan-specs.ps1` | Check Orphan Specs |
361
362
  | `check-orphan-specs.sh` | Orphan Spec Detection Script |
@@ -386,6 +387,7 @@
386
387
  | `fix-manifest-paths.sh` | Manifest Path Fixer |
387
388
  | `generate-adoption-skills.mjs` | Self-Adoption Skill Copy Generator and Drift Gate |
388
389
  | `generate-docs.mjs` | Look up the release date for `version` from CHANGE |
390
+ | `generate-hook-fingerprints.mjs` | Generate the table of hook script contents UDS has |
389
391
  | `generate-llms-txt.mjs` | llms.txt Generator and Drift Gate — XSPEC-385 |
390
392
  | `generate-locale-coverage.mjs` | Locale Coverage Generator |
391
393
  | `generate-version-manifest.mjs` | Generate Version Manifest (SPEC-SELFDIAG-001 REQ-9 |