05-测试-文档退版与生成器反向回退法

适用场景

当一份由脚本生成的交付文档/报告需要退版（退回上一版本）时——
触发原因可能是用户指令回滚、口径失真、或新版本未取得确认。

关键点：退版不是"把新产物删掉"就结束了。交付物是生成器脚本的产物，
只要生成器里那批口径补丁还在，下一次重跑就会把失真版本原样再生一遍——
退版等于白做，而且会以"看起来是新生成的"面貌复活，更难发现。

本条与 05-测试-时点快照报告不整体重生成与增量升版法 是同一枚硬币的两面：
那条管正向升版（时点报告不整体重生成、走增量），本条管反向退版（产物与生成器同步回退）。

操作步骤

1. 先判定是否真需退版：退版理由必须是可陈述的（用户指令回滚 / 口径失真 / 未确认先执行）。
   锚点：.workbuddy/memory/2026-10-05.md L42（用户指令「还原刚才更新和删除的部分」）。
2. 产物退版：旧版产物移入 .workbuddy/trash_<日期>/，目标目录只留退回后的那一版。
   锚点：.workbuddy/memory/2026-10-05.md L44（v1.2 移入 .workbuddy/trash_20261005/）。
3. ★生成器反向回退（本条核心）：定位生成脚本，把该版本的口径补丁逐项反向回退——
   不是删档，是把脚本里的数值与文案改回上一版。
   锚点：tools/build_assess_report.py（v1.2 口径补丁全部反向回退）。
4. 枚举回退项清单，四类逐项过：① 版本号 ② 规模数字 ③ 维度分值 ④ 未闭环项文案。
   锚点：.workbuddy/memory/2026-10-05.md L44（版本号、规模数字、制度维度 92→85、未闭环项文案）。
5. 编译校验：改动后 py_compile 必过，否则退版引入新故障。
6. 重跑验证：明确写出"重跑只会产出退回版，不会再生失真版"——这是退版真正闭环的判据。
   锚点：.workbuddy/memory/2026-10-05.md L44（py_compile 通过 → 重跑只会产出 v1.1）。
7. 划清"保留未回滚"边界：属用户先前明确指令产出的，不纳入本轮回滚范围，并显式列出。
   锚点：.workbuddy/memory/2026-10-05.md L45。
8. 留痕：当日日志记退版原因与旧版备份落点；若该口径进了技能包/手册/记忆，一并同步。

注意边界

• 产物与生成器必须同一次退完：只动产物不动脚本，等于埋一颗"重跑即复活"的雷。
• 被占用文件不可强删：回收站机制对 docx 可能报失败，连 rename 也会因占用失败——
  此时只能等持有进程释放，禁止强行删除。
  锚点：.workbuddy/memory/2026-10-05.md L40。
• 改动半径只限被点名对象：借退版之名顺手改其他内容是违规的。
• 降敏不因退版而放松：退版过程中新增的样例、说明仍须代号化（U1–U4 / E1 / C1C2）。
• 备份先行：退版前旧版必须有明确落点，且落点可复查。

反例避雷

• ✗ 只删产物、不回退生成器（本条要防的头号坑）：v1.2 删了，但 build_assess_report.py
  里的 v1.2 补丁还在 → 下次重跑立刻再生一份"新出炉的 v1.2"，且因是新产物更难被识别为旧口径。
  解法：产物移走 + 脚本补丁反向回退 + 重跑验证三件事一起做完。
• ✗ 只回退版本号、不改口径数字：版本号退回 v1.1 但正文里的 92 仍是新口径 → 名实不符，
  比不退更糟。解法：版本号/数字/维度/文案四类逐项列清单过。
• ✗ 占用态强删：回收站失败后改用 os.remove 硬删 → 可能删不掉或破坏正在打开的文件。
  解法：等进程释放；实在不行标注"待释放后重试"挂起。
• ✗ 退版后忘记同步记忆/手册：日志写了、记忆里还是失真口径 → 下次照旧口径写。
  解法：按影响面四类（代码配置 / 文档手册 / 技能包总览 / 记忆与自动化）穷举同步。
• ✗ 把退版当撤销键反复横跳：未先消歧就升版、再退版、再升版 → 整轮空转。
  解法：升版前先确认口径（见 00-总纲-不可逆语义判断歧义消解与确认前禁动手法）。

代码锚点 / 实战战绩

• .workbuddy/memory/2026-10-05.md L42-46（第六节 回滚：完整退版记录）
• .workbuddy/memory/2026-10-05.md L40（占用态不可强删）
• tools/build_assess_report.py（生成器，v1.2 口径补丁反向回退的落点）
• .workbuddy/trash_20261005/（旧版产物落点）
• 战绩：2026-10-05 评估报告 v1.2 → v1.1 退版，生成器补丁四项全部回退，py_compile 通过，
  重跑只产 v1.1；同轮 24 份去重文件按原路径还原 0 失败，库内 docx 116 → 140 恢复原状。
• 附包体检器 scripts/doc_rollback_check.py：对 2026-10-05 真实退版记录跑 PASS；
  「v1.2 已删除，退回 v1.1」一句话式记录 FAIL×5（可自检：python doc_rollback_check.py --selftest）。

关联笔记

• 反向配套：05-测试-时点快照报告不整体重生成与增量升版法（正向升版口径）。
• 影响面穷举：00-总纲-前序结论证伪与产物连锁订正法（退版常由结论证伪触发）。
• 前置约束：00-总纲-版本纪律规则（只留最新版、旧版备份后精确删除）。
• 长期记忆：MEMORY.md 六「交付/文档/图形纪律」。

版本记录

• v1.0.0（2026-10-22）首版：从 2026-10-05 评估报告退版复盘抽象；核心判据＝产物与生成器同步回退 + 重跑验证。