dsh-vibe-math 2.2.0 → 2.2.2

package/AUDIT-CHECKLIST.md

@@ -0,0 +1,163 @@
+# 全面检查（audit）必查清单
+
+> **本文件是强制流程，不是建议。** 每次对本仓库做"全面检查 / 找 bug / 优化"时，
+> **必须**逐项过一遍本清单。清单的来历是一次真实事故：v2.1.0 在实地测试中，
+> 每个成员收到的提示词都写错了身份，而当时 123 条断言 + 15 个灵敏度探针**全部通过**。
+> 事故的根因不是某一处代码写错，而是**审计维度本身漏了一整类**——没有人检查"成员读到的文字"。
+
+---
+
+## 0. 铁律
+
+1. **成员读到的文字就是产品。** 提示词（人设 / 状态块 / 每轮问句 / 收件框头 / 回执契约）
+   必须像函数返回值一样被断言。任何只检查工具返回值、投影状态、文件内容的测试，
+   对提示词缺陷是**盲的**。
+2. **身份一律显式传递，绝不猜测。** 禁止从"最近唤醒的成员""列表第一个"之类的全局状态推断
+   "这段文字是写给谁的"。宁可显式失败（`V5_INTERNAL`），也不要生成一段身份错误的提示词。
+3. **测试脚本必须完整保留交互信息。** 断言之外，还要把交互原文落盘成可人工复核的语料
+   （见 §2.4）。"退出码 0"不是验收，"人能读到正确的原文"才是。
+4. **探针必须真的能变红。** 一个灵敏度探针如果始终为绿，说明它守的那条不变式**其实没被测到**——
+   这比没有探针更糟（它给人虚假的安全感）。
+
+---
+
+## 1. 第一优先：提示词分配与交互内容
+
+**这一节是最高优先级。历史上最致命的缺陷全部出在这里。**
+
+### 1.1 身份分配
+
+- [ ] 每条提示词里的身份（`[状态] 你是 X`）= 这条提示词**实际发给的成员** X？
+- [ ] 表头里的身份（`【… —— <职位> <代号>】`）= `[状态]` 里的身份？
+- [ ] 随行人设（persona）指向的资料库路径 = 该成员自己的（`Members/<该成员>/`）？
+- [ ] 人设里的代号/职位 = 实际职位？
+- [ ] 有没有任何地方从**全局可变状态**推断身份（`currentMember`、`list[0]`、闭包快照）？
+- [ ] 成员**创建/唤醒的时序**：构造提示词时，该成员是否**已经**被写入权威状态？
+      （先落盘、再构造；顺序反了会得到"上一个成员"的身份与"加入前"的编制）
+- [ ] 全文有没有 `?` / `undefined` / `NaN` / `[object Object]` 之类占位垃圾？
+- [ ] 一条提示词里是否**只有一个**身份声明（不能出现两段互相矛盾的身份）？
+
+### 1.2 编制 / 名额 / 门槛
+
+- [ ] `[在册]` 是否包含读者**自己**？
+- [ ] `[在册]` 是否与权威编制一致（不多、不少、无重复）？
+- [ ] "有表决权者 N 人"是否等于 `[在册]` 里真正的表决者数（临时工不算）？
+- [ ] `m = min(quorumCap, N)` 是否与状态块里报的一致？
+- [ ] 未就位/失败/已除名的成员有没有被**如实**呈现（不能静默略去，也不能混进在册）？
+- [ ] 轮次号在表头与状态块里是否一致？
+- [ ] 编制变动（雇佣/解雇/增聘常驻）后，后续提示词是否立刻反映新编制？
+
+### 1.3 名称与领袖叙事
+
+- [ ] 章程/人设里出现的**每一个代号**是否都真实存在于当前编制？
+- [ ] 有没有**硬编码**的代号（例如写死 `acad`），而实际编制可能不同？
+- [ ] 当某种职位根本不存在时（例如 `academician:false`），章程是否仍然声称它存在、
+      要求成员向它汇报、或承诺它会派活？（这是"指向一个不存在的人"）
+- [ ] 章程是**入职快照**还是每次重建都改写？如果它自称"你入职时的…"，就必须冻结在入职时。
+
+### 1.4 交互内容（消息 / 群聊 / 会议 / 辩论 / 分派 / 雇佣）
+
+- [ ] 每条送达消息的**框头署名 = 真实发送者**？（尤其：所办 ≠ 院士；不能署"最近唤醒的成员"）
+- [ ] 框头**类型**是否正确？（私信 ≠ 致全体表决者；督办 ≠ 分派；所办分派 ≠ 院士分派）
+- [ ] 系统/框架自己发出的反馈，**发送者**是否是框架自己（而不是"该成员发给自己"，
+      那会被自消息校验拒掉、静默失效）？
+- [ ] 一次提示词里，**同一条消息是否只出现一次**？（先 ack 再构造，否则会投递两遍）
+- [ ] 会议提示里"其他人的发言"是否只列**别人**、且用真实代号？
+- [ ] 表决提示里的对象、陈述、历史票是否与该对象真正对应？
+- [ ] 转述/中继的消息（提议开会、增聘、临时工意见、反对分派）是否署**真实发起人**？
+- [ ] 分派/督办里"由谁分派""谁督办"是否与真实调用者一致？
+- [ ] 人可读镜像（编制表、任务板、会议纪要、辩论录、结案）里的代号/职位/雇主是否正确？
+- [ ] **回执契约**：框架实际处理的每个字段，是否都在 `replySpec` 里出现且按职位裁剪？
+      （藏起来的字段 = 不可发现的通道）
+
+### 1.5 时序与幂等
+
+- [ ] 重放同一事件（`subagent/end` 重复、重复提议）会不会产生**重复**的交互内容？
+- [ ] 成员被解雇/失败后，还会不会收到后续消息？
+- [ ] 会话重建（resume）后的提示词，措辞是否与"新入职"区分开？
+
+---
+
+## 2. 第二优先：把上面每一条变成**会变红**的测试
+
+### 2.1 逐条断言，而不是抽查
+
+对**每一条**捕获到的提示词都跑一遍通用扫描（身份一致性、编制一致性、无垃圾、无重复投递），
+而不是只挑几条看。给出**精确的期望值**（例如 4 名创始成员各自的 `[在册]` / m / 表决者数），
+而不是"包含某些关键词"。
+
+### 2.2 期望值要能证伪
+
+- 断言"此时**还没有**定论"时，**必须**同时断言"这一轮真的走完了"（例如断言阶段已推进到
+  `debate`、或恰好收齐 N 张票）。否则预算不足会让"还没有"**无条件成立**，
+  无论规则被破坏成什么样。
+- 断言顺序：先确认前置状态已达成，再断言结果。
+
+### 2.3 用例互相隔离
+
+每个用例用**独立的会话根/工作区**，并在结束时暂停它。
+否则一个用例遗留的心跳/会议/验证会污染下一个用例（表现为"某个用例莫名其妙收不到唤醒"）。
+
+### 2.4 保留交互语料（**强制交付物**）
+
+测试脚本除了断言，还必须把**框架真正发出的每一条提示词原文**落盘：
+
+- 机器可读（JSON）+ 人可读（Markdown）；
+- 覆盖全部交互类型（入职、重建、常规轮、心跳、表决初评/辩论、会议、提议、各类框头、框架提示、失败）；
+- 把工作区路径归一化（如 `<WS>`），使语料**确定性、可 diff**；
+- **随包发布**，作为人工复核提示词正确性的入口——复核者不必去翻会话日志。
+
+### 2.5 每个不变式都要有灵敏度探针
+
+- [ ] 每个"提示词/交互"不变式，都有一条探针**故意打破它**，并要求对应套件**变红**。
+- [ ] **探针必须真的启动被测套件**：检查工作目录/路径解析。
+      曾因工作目录被百分号转义（Windows 中文路径 + `URL.pathname`）导致子进程**全部启动失败**，
+      "非零退出"被当成"探测成功"——整份审计是假的。
+- [ ] **探针必须被目标套件真正读取**：曾因某个 e2e 套件**不读** `V5_PLUGIN` 环境变量，
+      针对它的探针跑的是**未变异**的插件，恒为绿。
+- [ ] **变异必须真的改变行为**：很多守卫是互相遮蔽的，删掉其中一个其实是**语义惰性**的
+      （例如同一规则在三处重复检查，只削弱一处仍会被另外两处挡住）。
+      这类变异不能做探针——它会让审计误报"盲点"。
+- [ ] 探针**不得引入语法错误**：语法错误导致的非零退出同样是"假红"。
+      每条变异都应能被 `node --check` 通过。
+- [ ] 对**不可达**的守卫（设计上互斥、永远不会进入的分支），**不要**留一个永远为绿的探针；
+      要么写行为可观测的等价探针，要么显式删除并在脚本里注明原因。
+
+---
+
+## 3. 一个高效的补充手段：**把不变式写成文档/图，再拿它去对代码**
+
+本次修复中最后找到的一个真实缺陷（会议与验证的"互斥"只做了单向）就是这么被发现的：
+为 v5 画架构图时，被迫把"会议与验证互斥"写成一句**明确的不变式**，然后拿这句话去逐条对照代码 ——
+发现 `startMeeting` 有守卫、`armNextVerify` 没有。单看任何一处代码都不觉得有问题，
+是"写下不变式 → 双向核对"这个动作把它逼了出来。
+
+所以：
+
+- [ ] 画架构图/写规格时，**每一条箭头与每一个"互斥/永不/必须"的措辞都要落到代码里核对**，
+      特别是**成对出现的关系**（互斥、双向、唯一、幂等）——只做一半是最常见的形态；
+- [ ] 文档里凡是出现"二者互斥""永不同时""必然"这类断言，都要问一句**它在代码里由谁保证**；
+      若答案只在一个方向上成立，那就是缺陷；
+- [ ] 相对顺序**不可观测**的地方（因为互斥）不要写成精确的优先级列表假装精确，
+      而要写明"二者互斥，故顺序无关"。
+
+---
+
+## 4. 第三优先：其余（沿用既有做法）
+
+- [ ] 静态自检：调用了但未定义的函数、未声明的参数键、不存在的会话 API 方法、
+      已文档化但从未抛出的错误码、遗留的开发标记。
+- [ ] 需求可追溯：方案里列出的工具名、参数名、理念条目，代码里是否都存在。
+- [ ] 失败路径：看门狗、幂等、崩溃恢复、降级后端、配额、越权。
+- [ ] 全量回归：**所有**历史套件，且逐个检查退出码（不要用管道截断输出，
+      管道会吞掉退出码或造成 EPIPE）。
+- [ ] 发布产物自证：不是"publish 退出 0"就算完成——要从 registry 取回 tarball，
+      核对 shasum、逐字节比对插件、确认修复标记存在、并在**已发布包内**跑一遍套件。
+
+---
+
+## 5. 汇报要求
+
+- 缺陷要分**类**："这一整类此前没有审计维度"比"修了 N 个 bug"更重要。
+- 假绿/假红必须单独说明：**审计本身失效**是最严重的发现。
+- 每条结论都要给出**可复核的证据**（真实日志片段、语料原文、可重跑的命令与结果）。