SOP：`merge-guard` 判据 I 修复（补 `separated`）+ 总账三条更正¶

主题目录：merge-guard-i-20261007/｜变更日期：2026-10-07｜用户指示「执行」

1. 背景¶

前一轮过账时把挂账 #35「改-验循环缺实时提醒」留在待办里，并给它补了量化依据。用户追问「I 是什么操作」后核实发现：

#35 的前提已不成立：其实时性已由 merge-guard 判据 I 承担（10-07 上线、强制级，比 #35 想要的"提醒"更硬）。判据 I 就是「文档类 Edit/Write ×只读 RunCommand 交替」的实时拦截，正是 #35 所想。写 #35 时（10-06）判据 I 尚未上线，属时序重叠造成的重复挂账。
判据 I 自身有误报缺陷：初版只做「6 次窗口内计数」（n_edit ≥ 3 且 n_ver ≥ 2）， 未做 A/B/C/D/E 都有的「分属不同步」（separated）检查 → 同一条消息里已经合并好的并行批（并行改 3 个文档 + 并行跑 2 条只读命令）也会被强制拦截。 实测证据：logs/guard_events.jsonl 中 03:38:41 与 03:38:42 两条 allow_fp I 相隔 1 秒，正是"同一步内的并行调用被拦 → 随即原样重发"的形态；I 的放行率因此达 3/6 = 50%。

2. 目标¶

修 I 的误报：计入项必须两两「分属不同步」（间隔 ≥ STEP_GAP_SEC），与 A~E 口径对齐；修复后「已合并的并行批」不再被拦，真碎步序列仍被拦；
总账三条更正：关闭 #35（移入已做 #39）；明确不做代码类扩展、不把判据 C 升强制；新增待标定 #40（观察 I 修复后的放行率）；
不改变 I 的强制属性与放行机制（指纹放行 + 每会话上限三重兜底不变），只收窄命中面。

3. 前置条件¶

可写 merge-guard/merge-guard.py 与总账；
python3 可用；
判据 I 的改动即时生效（本机实测：改 hook 脚本同会话下一次调用即按新逻辑走），故必须先离线验证再改。

4. 影响范围¶

项	说明
涉及对象	`merge-guard`（PreToolUse 强制拦截 Hook）、全局优化总账
是否停服	否；无窗口要求
行为变化	判据 I 命中面收窄（并行批不再触发）；其余 7 条判据与放行机制不变
风险面	改动即时生效且作用于所有工具调用 → 语法/逻辑错误会波及每一次调用，故验证前置
不受影响	`ENFORCE_MARKS`（I 仍在强制清单）、指纹放行逻辑、每会话 `DENY_MAX` 上限

5. 分步操作¶

步骤 1：备份（高危前置，必做）¶

TS=$(date +%Y%m%d-%H%M%S)
D=~/Documents/services/token_proxy/merge-guard-i-20261007/backup
mkdir -p "$D/home/rain/Documents/services/token_proxy/merge-guard" \
         "$D/home/rain/.trae-cn/skills/ops-execution-efficiency/references"
cp -p ~/Documents/services/token_proxy/merge-guard/merge-guard.py \
      "$D/home/rain/Documents/services/token_proxy/merge-guard/merge-guard.py.bak.$TS"
cp -p ~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md \
      "$D/home/rain/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md.bak.$TS"

步骤 2：改判据 I（三处，必须成套）¶

坑：这里与"三处取时点"同理——改动必须成套，且 involved 与 n_edit/n_ver 必须同源（都从 involved 里数）。若 n_edit 仍从 win 数、spread 从 involved 算，会出现"计数含并行项、spread 只看其中一部分"的错位判断，而这种错位不会报错、只会静默误判。

文档头判据说明：改为「Edit/Write 命中 DOC_EXTS ≥3 且只读 RunCommand ≥2（6 次窗口内、且两者分属不同步）」；
_detect() 的 I 段：先筛出 involved（文档编辑 + 只读命令），计数与 spread 均基于它；
注释写清"为什么补 separated"与实测证据（03:38:41/42）。

cd ~/Documents/services/token_proxy
python3 -m py_compile merge-guard/merge-guard.py && echo "语法通过"
grep -n "involved\|spread" merge-guard/merge-guard.py     # 预期：I 段各出现数次

步骤 3：离线验证（先验后生效）¶

构造 tail 序列直接调 _detect，不写 state、不触发 Hook：

cd ~/Documents/services/token_proxy
python3 merge-guard-i-20261007/verify_i_separated.py; echo "退出码=$?"

预期：全部通过（0 项失败），共 12 项——7 项针对 I（分步触发 / 并行批不触发 / 混合不触发 / 编辑不足 / 命令不足 / 非文档扩展名 / 非只读命令不计入），5 项为既有判据回归（A/B/D/E + I 仍在强制清单）。失败判断：② 或 ③ 未通过 → spread 未生效（核对是否从 involved 取值）。

步骤 4：总账三条更正¶

1.1 节删除原 #35 行（改-验循环提醒）；
第二节新增已做 #39（关闭 #35，理由：判据 I 已覆盖 + 不做代码类扩展 + 不升 C）；
第五节新增待标定 #40（观察 I 修复后的放行率；若仍 ≥50% 则降回提醒级）。

python3 - <<'PY'
import importlib.util, os
spec = importlib.util.spec_from_file_location("inj", "sessionstart-hook/session-start-inject.py")
m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
led = os.path.expanduser("~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md")
print("挂账(1.1) =", m._backlog_count(open(led, encoding="utf-8").read()))   # 预期：5
PY

6. 验证¶

层级	命令	预期
语法	`python3 -m py_compile merge-guard/merge-guard.py`	无输出
判据逻辑（12 项）	`python3 merge-guard-i-20261007/verify_i_separated.py`	全部通过
既有判据回归	同上 ⑧a~⑧e	A/B/D/E 仍触发、I 仍在 `ENFORCE_MARKS`
真机	修复后观察 `logs/guard_events.jsonl` 中 `mark=I` 的记录	并行批不再出现 `allow_fp I`；放行率应自 50% 回落（观察项 #40）
总账	步骤 4 的命令	挂账 5

7. 回滚¶

备份位置： - merge-guard-i-20261007/backup/home/rain/Documents/services/token_proxy/merge-guard/merge-guard.py.bak.20261007-075345 - merge-guard-i-20261007/backup/home/rain/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md.bak.20261007-075345

台账见 backup/README.md。

cp -p ~/Documents/services/token_proxy/merge-guard-i-20261007/backup/home/rain/Documents/services/token_proxy/merge-guard/merge-guard.py.bak.20261007-075345 \
      ~/Documents/services/token_proxy/merge-guard/merge-guard.py
cp -p ~/Documents/services/token_proxy/merge-guard-i-20261007/backup/home/rain/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md.bak.20261007-075345 \
      ~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md
python3 -m py_compile ~/Documents/services/token_proxy/merge-guard/merge-guard.py && echo "回滚后语法通过"

回滚后验证：跑 verify_i_separated.py，其中 ②/③ 应失败（旧版会拦并行批）——这正是回滚成功的标志。总账回滚后挂账回到 6。

8. 风险说明¶

风险	缓解
Hook 改动即时生效且作用于每次调用	先离线验证（12 项）再交；`_detect` 无副作用；脚本整体异常静默 `exit 0`
`involved` 与计数不同源导致错位判断	本次统一从 `involved` 取；验证用例 ②/③ 专门覆盖该形态
收窄过头导致真碎步漏拦	用例 ① 保留"分步序列必须触发"；真机由观察项 #40 跟踪放行率
已有自动放行机制被破坏	未触碰指纹放行 / `DENY_MAX` / `INJECT_MAX`；⑧e 断言 I 仍在 `ENFORCE_MARKS`
总账编号冲突	1.1 删一行（#35）、第二节新增 #39、第五节新增 #40；编号在各自节内唯一

附录：交付物清单¶

文件	说明
`merge-guard/merge-guard.py`（改）	判据 I 补 `separated` + 文档头说明
`optimization-backlog.md`（改）	1.1 删 #35；第二节 + #39；第五节 + #40
`merge-guard-i-20261007/verify_i_separated.py`	离线验证（12 项，可重复运行）
`merge-guard-i-20261007/SOP.md`	本文档
`merge-guard-i-20261007/backup/`	两个文件备份与台账

来源：/home/rain/Documents/services/token_proxy/merge-guard-i-20261007/SOP.md ｜最后更新：2026-10-07 07:54（由 build/sync.py 同步，请勿在站点侧修改）

SOP：merge-guard 判据 I 修复（补 separated）+ 总账三条更正¶