# 任务书 11：已完成模块的收尾

把已完成的几个模块里剩下的问题改掉，然后再开始写 flow。一共三件：

1. 假设专用指标的名字加候选前缀；
2. 消融重做时，实验员从上一次交的代码接着改；
3. 判重问题的说明里补上"关键设定"。

本任务书已由用户和监督者在 2026-10-03 一起确定。下面说的"监督者"，是在参考项目目录里和用户讨论设计的另一个会话。

## 开工前先读

- `CLAUDE.md`：全部，尤其是"罕见情况怎么办"、"不设默认值"、"测试"。
- `docs/方法.md`：
  - 第五部分"指标"：登记、引用、测不到时怎么办；
  - 4.3 ⑥：冻结协议包括什么；
  - 4.3 ⑨ ⑯：修复、消融重做。
- `docs/结构.md` 第八部分：vocab、materials、submissions、tasks、jev 各节。
- `WORK_LOG.md`："未完成"里"同一轮两位研究者可能给假设专用指标起同一个编号"那条，以及"给 flow：消融格核验不通过……"那条。

## 一、假设专用指标的名字加候选前缀

**问题**：同一轮里，研究者之间互相看不到提案，会给假设专用指标起同一个名字、定义却不同。两份都会收下，下一轮有人引用这个名字时，程序取第一条定义，悄悄用错。

参考项目的真实账本里出过 5 次，都是同一轮、不同研究者：
- 11-real-1 第 1 轮 min-radius；
- 15-real-1 第 1 轮 lp-polish-gain；
- 15-tight-2 第 2 轮 final-radius-spread 和 last-improve-elapsed；
- 16-real-1 第 2 轮 restart-gain。

监督者核对过 16-real-1 那两条：一条算"重启段内最好 Σr 减进入重启段时的 Σr"，另一条算"最终 Σr 减池阶段最好 Σr"，是两样东西。

**改法**（用户 2026-10-03 选"冻结时加候选前缀"）：
- 研究者在提案、回应、统一里登记新指标时，只写短名。短名恢复"不能含 `.`"这一条，写进 vocab 的字段定义和字段说明。
- 冻结时，冻结协议里新登记的指标改用全名"候选编号.短名"，例如 `r2-c1.restart-gain`。候选编号判重合并之后才有，所以只能在冻结时加。
- 冻结之后一律用全名：
  - materials 的已登记指标清单、能引用的清单（对号清单的 `reusableMetrics`）；
  - 研究者引用别人的指标时，`metrics.reused` 写的全名；
  - 实验员材料里"要实现的指标定义"；候选代码在结果文件里也用全名当键写取值；
  - jev 查代码改动时对照的指标。
- 已占用的名字（对号清单的 `takenMetricIds`）只剩最终指标、常规辅助指标、两个保留键。全名都带 `.`，短名不带，两者不可能撞，所以已登记的那些不用再放进来。
- 加前缀只写在一处：在 materials 里，和 `FrozenProtocol` 放在一起写一个函数，输入 submissions 交回的冻结协议主体、候选编号、轮次、基线、合并了哪些原提案，交回 `FrozenProtocol`。flow 写冻结协议时调用它。
- tasks 读结果文件是按指标的 `id` 取值的，传进来的就是全名，按理不用改。改完后用一个带全名指标的测试确认一下。

同一个候选里，新登记的短名和引用的全名不会撞：一个带 `.`，一个不带。

## 二、消融重做从上一次交的代码接着改

用户 2026-10-03 定：消融格没通过核验、退回重做时，实验员从上一次交的这一格代码接着改，和正向修复一样。

举例：格 p2 第一次交上来，核验员说 p3 也被误关了。实验员拿上一次交的那份代码，只把 p3 恢复回来。

- materials 现在写的是"你的工作目录是完整代码的副本"，改成"上一次交的这一格代码的副本"。能读的代码版本里加上这一份，完整代码照旧列出，作为对照。
- 重做时消融核验看的改动全文，仍然是"这一格的代码相对完整代码"。这是 flow 传进来的，materials 不用管。
- 删掉 WORK_LOG"给 flow"那条里"实验员从哪份代码出发，方法没写"那半句，改写成：flow 重做时，把上一次这一格的提交取出来当工作目录。
- 方法.md 4.3 ⑯ 由监督者补写，你不用改。

## 三、判重问题的说明补上关键设定

任务书 10 已经把关键设定加进了判重的材料，但问题说明里还写着"每个因子有 `name` 和 `method`"（`src/jev/questions.ts` 第 33 行附近）。补上 `keySettings`，用一句话说明它是什么，其余措辞不动。

问题的指纹会因此变，这是预期中的：Jev 还没有校准过（WORK_LOG"Jev 校准"），没有旧数据需要对得上。

## 四、测试

- **前缀**：
  - 同一轮两个候选各登记一个同短名、不同定义的指标，冻结后是两个不同的全名；下一轮的能引用清单里两个都有，各自对应自己的定义；
  - 短名带 `.` 时退回；
  - 引用写短名而不是全名时退回，退回原因里列出能引用的全名；
  - tasks 用全名读结果文件，读得到值。
- **消融重做**：重做材料里写的工作目录是上一次的这一格代码，能读的版本里有它，也有完整代码。
- **判重说明**：jev 的不花钱测试里，问题文字里出现 `keySettings`。
- 改了 jev 的问题文字，跑一次 `npm run test:jev -- jev-latest`，确认判重那一问照常拿回概率。

不另派子 Agent 审阅：这三件都是按已经定好的写法改，范围小。

## 五、规模与文档

- materials 目前 1850 行，正好在上限上。尽量不超；超了就在报告里说明多在哪几处，监督者再和用户商量。
- 完成后更新：
  - `docs/结构.md` 第八部分：vocab、materials、jev 各节改了的地方；materials 一节补上加前缀的函数；
  - `WORK_LOG.md`：在"已完成"补一条；删掉"未完成"里指标重名那条；按第二部分改写"给 flow"那条。
- 不新建 md 文件。

## 六、验收与报告

做完后本地提交，然后在回复里交一份报告，监督者会对着实际文件逐项核对：

1. 提交号，修改的文件列表，每个文件的行数，materials、submissions、vocab 的总行数。
2. `npm run check`、`npm test` 的完整输出，`npm run test:jev -- jev-latest` 里判重那一问的结果。
3. 一份冻结协议加前缀前后的样子：两个候选登记同一个短名的例子。
4. 你和这份任务书、结构.md、方法.md 不一致的地方，以及为什么。
5. **规则不清楚的地方**：哪里让你犹豫、哪里你是靠猜的。没有就写"没有"。没有真实证据的可能情况，在这里提一句就够，不写进 WORK_LOG。