docs(skills): 补齐「跟到合并为止 / CI 诊断纪律 / 生成物同步」四类 PM 经验 (#4892)

[os-zhuang]

Fixes #4892

2026-08-03 的 v17 协议变更派发里,有四类已经付出过代价的经验,现行 skill 里没有或只写了半截。

⚠️ 先说与 #4885 的关系:同日同文件的第二次沉淀,已逐条去重

本单开出来时 origin/main 刚跳到 e2086fef0 —— PR #4885(issue #4882,另一 PM 会话),「增补 2026-08-03 运行沉淀的八条 PM 操作经验」。同一天、同一份 skill、同一类工作,挂在不同 issue 号下。

这正是本单新增的第 8 条要写的那条规则的现场实例:duplicate-fix-guard.yml 只在两个 PR 声明同一个 Fixes #N 时开火,跨 issue 号的同类工作它看不见。

所以本单先读完 #4885 全文再动笔,重叠的一律不重写:

条目	#4885 已覆盖?	本单处置
队列判据看 gh-readonly-queue/*	✅ 覆盖,且角度更准(auto_merge 字段入队后回落为 off)	不重写,只补三点
rerun_failed_jobs 复用原 ref	❌	新增 note 5
os-regen 入队前整体重生成	❌ 完全未覆盖	新增「入队与落地」小节
CI 日志诊断三条	❌	新增 note 7
跨 issue 号的基础设施撞车	❌	新增 note 8
读数纪律三条	❌(它的 note 4 讲「在哪棵树上读」,本条讲「命令是否在回答你以为的问题」)	新增 note 6
ratchet 可见性按路线相反	❌	进 spec-property-retirement

---

1. pm-dispatch —— Operational notes 四条 → 八条

note 5:rerun_failed_jobs 复用原 run 的提交与合并 ref,不重算。
note 2 讲的是「同一签名再现要重新诊断」;这条讲另一半 —— 当红的原因是基上缺一个已经合并的修复时,重跑这个动作本身就无效。#4852 的 CI 红在止血 PR #4856 落地之前,重跑仍是同一个 5000ms,直到 git merge origin/main 推了新提交才拿到新的合并 ref。它因此在队列外空转 100 分钟。 判别方法:比对那个修复的合并时间与本 run 的创建时间。

明确写了与 rerun-safety-nightly.yml 无关 —— 那个查的是「同一 checkout 跑两遍是否自洽」的测试污染,名字像但不是一回事。

note 6:读数纪律 —— 三条各自产出过一个「我信了并据此行动」的错读数。

• cd X && cmd 短路:cd 失败时整条命令继续,在当前仓里执行,产出假的「objectui 零消费方」。⛔ 跨仓一律 git -C。
• git grep -c | wc -l 数的是文件数不是命中数。
• 裸名 grep 被幸存家族当子串命中(system/EmailTemplate → EmailTemplateDefinition)。退役核验要带引号精确名;更硬的判据是查声明式而非提及 —— 注释 / pin 断言词 / 迁移散文里出现该名是正常且应当的。
• 统一原则:零命中必须用确定存在的邻近词反查,否则不成立。

note 7:CI 红了先取完整日志归档 —— 三条读日志的纪律。
当天最贵的错误:公开断定四次 CI 红是内核 OOM-killer 杀掉 DTS 构建,据此开了 PR #4853,被 #4853 自己的 CI 推翻(挂着新参数跑,红得一模一样)。更正见 #4845。三个叠加错误各成一条:completeness check 绿 ≠ 测试通过;turbo 并发输出相邻 ≠ 因果;不要只看 tail(那次 ~10 KB 尾巴被 gen:schema 的 1675 行清单吃光)。并补:据错误结论开的 PR 要撤回 draft、解绑 Fixes。

note 8:共享基础设施类修复按症状复查 main,不按 issue 号。
写明 duplicate-fix-guard.yml 的覆盖边界(同仓 + 同一 Fixes #N),以及边界外的这一例:#4864 与 #4856 修同一个基础设施问题却挂不同 issue 号,而且 #4864 若合进去会把 #4856 已合的 60s 降回 30s —— 一次静默回退。

note 1 的三点补充(不重写它的主判据):「不在 main 上」是二义读数(同时兼容「排队中」和「没入队」,处置相反);队列分支 base sha 串成链,可读出排第几;转 draft 会同时掉 auto-merge 与队列成员资格。

2. pm-dispatch —— step 7 之后新增「入队与落地」小节

A. 碰生成物的 PR 入队前必须同步 + 整体重生成。 第 3 步只保证同一批内 file-disjoint,管不到先后两单都碰 packages/spec 生成物 —— 而协议变更几乎必然如此。merge=os-regen 会让 merge exit 0、零冲突标记却静默丢掉一侧改动,当天在 #4809 / #4846 / #4841 各复现一次。四步协议 + 一条更硬的旁证(去查上一单的实现体是否完好,条目是索引、实现体才是重灾区)。

B. 跟到 MERGED 为止,不是跟到「已入队」为止 —— 维护者对此有过明确纠正。落地之后再核一次落地判据本身,因为队列的合并同样走 os-regen 驱动。

3. spec-property-retirement

新增「四张 ratchet 的可见性按路线相反」:

形态	四张 ratchet	实例
枚举值收窄	字节完全相同,仪器上不可见	#4391(PR #4871)
整 def 删除	必须变化	#4834(PR #4878):−12 / −23 / −5

后果双向且都贵:前者的零变化判成异常 → 白折腾;后者的零变化判成正常 → 放过一个没真正删掉的 def。所以是先定路线再定期待读数,不能反过来。

顺手修掉一个悬空引用:第 2 节「nothing parses it」路线的先例指针写的是 packages/spec/src/kernel/plugin-runtime.zod.ts:243-248,该文件今天刚被 #4878 整体删除。改为指 #3896 / #4834(PR #4878)两个编号 + 幸存的 kernel/index.ts 说明块 —— 指 issue 比指行号耐放。

---

写进去的事实,逐条实跑核过

断言	核实来源
test 的 dependsOn 只有 ["^build"]	turbo.json 实读
packages/spec 无 pretest	package.json 实读
merge=os-regen 路径清单	.gitattributes 实读 —— 是 7 条不是 5 条,初稿漏了 docs/protocol-upgrade-guide.md 与 content/docs/references/**,已补,并注明权威清单是文件本身
「completeness check 绿 ≠ 测试通过」	原文在 .github/workflows/ci.yml:234
duplicate-fix-guard.yml 覆盖边界	workflow 实读

其他

• ⛔ content/docs/releases/ 一个字未碰。
• 空 frontmatter changeset —— 只改 .claude/skills/ 下两份内部 agent 说明,不含任何 workspace 包的代码或产物。
• 纯文档改动,无代码路径变化。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_0176qgxgCXTJCUv4YFLtusP9

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 3, 2026 1:39pm