# 接下来要做的事

写于 2026-09-22，2026-09-26 在 0.16.3 发布后更新。按优先级排，每条写清：为什么要做、做完是什么样、动手前要先弄清什么。

## 现状

- npm 上是 **0.16.3**（2026-09-26 发布，标记 `v0.16.3`）。下载回来拆包核对过，本次改动都在包里。
- 主干在发版之后只有文档更新（#150 README、#151 本文件及其审查修正），没有未发布的功能改动。
- 自动检查：每个 PR 跑 `scripts/` 下 138 份，另有不阻断合并的历史兼容夹具任务跑 `experiments/` 下 24 份；发版时由 `cm-release-smoke.sh` 补跑 CI 跑不了的 7 份。
- 盘点脚本 `scripts/audit-untested-enums.mjs` 报告：**24 个取值缺覆盖，分布在 22 处**（上次记录为 38 个、40 处）。
- 已在真实环境验证：「已审交接后 QA 卡住的任务作废重跑」在 e2e 存量项目和全真模型临时项目上各跑通一次（2026-09-25）；公司项目上的原始事故尚待维护者本人跑一次确认。

---

## 第一档：补测试（清单里的 A 类，剩 0 条，已完成）

详细清单在 `docs/untested-branches.md`。cm-refactor 最后两条已补，A 类清单全部完成；这不代表 B 类或脚本未识别的分支已有覆盖。

| 顺序 | 模块 | 要补的 | 为什么排这里 |
| --- | --- | --- | --- |
| 已完成 | cm-check | ~~`configured` 状态~~ | **已补**：`scripts/cm-check-host.test.mjs`，含三态、核心判定、非法报告及变异验证 |
| 已完成 | cm-fix | ~~诊断结论 `design_change`~~ | **已补**：`scripts/cm-fix-escalation.test.mjs`，含真实红测、升级归档、恢复幂等、QA 父子退出及变异验证 |
| 已完成 | cm-test | ~~中断后允许重做的 `snapshot` / `evaluation` 两种纯读步骤~~ | **已补**：`scripts/cm-test-session.test.mjs`，含重做与禁止重做、原结果回执校验、已完成步骤回放及变异验证；这两种是步骤种类，不是用户模式 |
| 已完成 | cm-refactor | ~~规则判定三态~~ | **已补**：`scripts/cm-refactor-gaps.test.mjs`，含三态及混合裁决、拒绝码、报告和规则传递、变异验证；规则缺失或错误却不修订手册（含仅改行尾空白、换行符及首尾空行）时，在报告发布及试点前拒绝，修订效果仍待独立审查 |
| 已完成 | cm-refactor | ~~四个失败码~~ | **已补**：`scripts/cm-refactor-gaps.test.mjs`，含真实冲突与恢复、保留外来字节、不重试，及普通失败恢复对照；unknown-effect 列表成员的变异由源码合同检查捕获，详见缺口清单 |

**每一条都要做到的**：

1. **先读懂再动手**。弄清那条分支本来该是什么行为，列成一张表（输入 → 结果）。读浅了会写出「形状对但没验到点上」的测试，比没有更糟。
2. **变异验证**。测试写完后，故意把被测代码改坏几种，确认测试会红；改完还原，`git diff` 必须为空。新写的测试本来就该过，过了不代表验到了点上。
3. **重跑盘点脚本**，确认那条确实离开了缺口列表，数字下降。
4. **更新清单**，把做完的划掉。

---

## 第二档：已拍板的设计问题

### 1. cm-fix 本地 unknown 步骤的显式放弃与重做（已发布于 0.16.3）

**决定**：保留所有 `unknown` 的默认不重派。仅对复现、诊断、测试编写与运行、修复、回归、复盘、走查及对应第二轮本地步骤，
在原运行中增加带原因和独立启动旗标的 `abandon_step`；每次保留旧 intent，追加绑定摘要的记录和日志，再用新的 retry ID 重做。
最多 8 次，红灯输出另存。确切允许清单见 [JS 控制文档](js-workflow-control.md#cm-fix-本地-unknown-步骤的人工放弃)。

独立根因/最终审查、Learning 写回、交接文件不适用：前者可能已有外部调用，后两者可能已写项目或规格文件。
最终审查仍走既有人工续审。驾驶员继续预检答案；普通 `advance`/`run` 不自动放弃。

---

## 第三档：已知缺口，值得做但不急

### 2. QA 修复子运行换会话恢复（已发布于 0.16.3）

cm-ai 的 V3 会话父运行用 `--original-host-context` 恢复后，QA 修复子运行也使用当前真实会话打开和签审查授权；已有子配置保持不变。新建子运行只接受当前会话或父运行的持久创建会话，runtime 仍须匹配。父子运行继续串行交接同一把锁，原逐项授权不变。

验证见 `scripts/cm-ai-qa-fix-cross-session.test.mjs`：真实父子存储、模拟审查程序覆盖 A 创建、B 签授权、C 恢复及非法创建、审查员独立性、运行时边界。旧 protected 兼容入口和 batch 不在此次范围。

### 3. 驾驶员推广到其它工作流

**现状**：九个 JSONL 宿主（cm-fix、cm-ai、cm-ai-batch、cm-check、cm-idea、cm-init、cm-prd、cm-refactor、cm-test）都已有单步驾驶员，共用 JSONL 传输核心。剩余缺口：cm-prd 的 PDF/HTML 材料执行器与 cm-test 的浏览器执行仍缺驾驶员 runner，会在发送前拒绝；cm-check 宿主无持久会话，驾驶员只能重新开始或只读 status，不能跨进程 resume。

**下一步**：补齐上述执行证据类 runner（PDF/HTML 读取、浏览器执行），证据必须来自实际运行；驾驶员的预检表仍须从各宿主的操作路由推导，不能照搬。

## 第四档：内部协议分支（清单里的 B 类）

**已完成**：B 类六项都已在 CI 执行的 `scripts/*.test.mjs` 补测试并完成变异验证。`gzip` / `zstd` / 未声明编码的回环测试由审查方在沙箱外运行通过，并做了 gzip 解码故意改坏的变异验证（注意 `cm-claude-probe` 整份测试只在 macOS 运行，Linux CI 上跳过）。明细见 `docs/untested-branches.md` 的已覆盖表。

---

## 已知限制（不打算修，但要知道）

- **受保护模式跑不了 `tsx` / `vitest` 这类命令**。它们要开本地 socket，而沙箱把这个和「联网」放在同一个开关下。放开就等于给测试命令开整个外网，不划算。替代写法见 `skills/cm-fix/references/js-host.md`。驾驶员在建运行前会预警。
- **有 7 份测试只在发版时跑**。它们要启动 Codex 沙箱，GitHub 的机器不给这个权限。已接进 `cm-release-smoke.sh`，发版必过；CI 里有一句断言钉死这 7 份的名单，不会悄悄变多。
- **盘点脚本只认一种写法**（`['a','b'].includes(x)`），`switch`、对象查表、`Set.has` 都漏掉了。所以「24」是下限。
- **读代码找不到所有问题**。0.16.1 修的四个缺陷全是跑真实项目跑出来的。拿工作流去跑真实项目，仍然是发现问题最有效的办法。

---

## 做这些事的规矩

这一轮踩过的坑，照这几条就能避开：

1. **先写会失败的测试，再修**。确认它红的原因就是要修的那个问题，不是测试自己写错了。
2. **补测试必须做变异验证**，见第一档。
3. **改了存档相关的逻辑，要拿真实的存量运行验一遍**。测试套件里没有「带着历史跑过头」的夹具，有一次改动就是靠打开真实存量运行才发现会让它打不开。
4. **提交前重新 diff 自己改过的每个文件**。别人（或别的会话）可能同时改过，有一次就是这样把没读过的代码合进去了。
5. **全套检查都跑**：`node --test scripts/*.test.mjs`、`./scripts/cm-check-runtime.sh`、`python3 scripts/validate-public-repo.py`、`python3 scripts/scan-public-safety.py`。
6. **合并后两端都重装**：`./install.sh --yes`（Claude）和 `./install-codex.sh --yes`（Codex），然后在安装目录里确认改动真的在。Codex 要开新会话才会加载新版本。
7. **源码在 `cm-workflow-dev`**，不是同名的另外两个目录。

---

## 发版

0.16.3 已于 2026-09-26 发布。下一版是否发、什么时候发，由维护者决定。

**流程**（0.16.1～0.16.3 都这样走）：改六处版本号（`package.json`、`VERSION`、`.codex-plugin/plugin.json`、README 两处、`docs/installation.md`）→ 把 CHANGELOG「未发布」切成新版本 → 跑全套检查和 `cm-release-smoke.sh` → 开 PR 合并 → 在 `cm-workflow-dev` 目录的终端 `npm publish` 并过两步验证（这一步必须本人做）→ 下载包核对 → 在发版提交上打标记 → 两端重新安装。

**README 的「最近更新」要重写正文，不能只换版本号**。0.16.0～0.16.2 发版时只替换了版本号，结果那段一直挂着 0.15.5 的内容，直到 #150 才改回来。

**注意**：npm 登录会过期。`npm whoami` 报 401 时，先 `npm login`，确认打印出 `aibyzero` 再发。过期时 npm 报的是 404「找不到包」，很容易误判成包出了问题。浏览器登录那一步超时时，可以改用 `npm login --auth-type=legacy`，在终端里依次输入用户名、密码和两步验证码。`npm publish` 过程中还会再弹一次网页确认，链接出来就尽快打开，别让它过期。