Claude Skill

cm-refactor

用户明确要求“只整理结构，不改变行为”时使用。执行边界分流、行为判官、分批重构和独立审查；缺陷修复转交 cm-fix，新增或变化的业务行为转交 cm-prd。

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download kingxiaozhe-cm-workflow-skills_cm-refactor-3f79f65.zip · 19 KB

kingxiaozhe/cm-workflow 27 0 forks MIT Updated 1d ago

Part of kingxiaozhe/cm-workflow — 24 skills

Install

skills CLI npx skills add https://github.com/kingxiaozhe/cm-workflow/tree/main/skills/cm-refactor

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kingxiaozhe-cm-workflow@llmmart

Git git clone https://github.com/kingxiaozhe/cm-workflow.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kingxiaozhe/cm-workflow collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

cm-refactor — 重构闭环（行为保持）

执行前读取 ../../runtime/project-context.md、../../runtime/orchestration.md、 ../../runtime/review.md、../../runtime/model-efficiency.md 与 ../../runtime/logging.md。Codex 入口为 $cm-refactor；Claude Code 跨平台入口为 /cm-refactor，macOS/Linux 另有历史别名 /cm:refactor。

用户明确要求外部专家，或为本次重构开启 AUTO 时，按 ../../runtime/external-expert.md 执行 ../external-expert/SKILL.md 的任务路由。重构写入、行为判官与审查保持 LOCAL；复杂方案比较可 CONSULT，权威事实可 VERIFY。外部结果只进入候选方案和风险清单，不得修改行为基线、代跑判官或满足独立审查。

用法:$cm-refactor {specs路径} {代码项目路径} 重构目标描述(哪块代码/为什么难维护)

JS 只读分流

在读取项目内容、解析角色、写 run_start、建立行为基线或修改代码前，先确认本轮有非空目标描述，并按下方“分流门”将意图归为 defect、behavior-change、gradual-adoption 或 structure-only；不要把描述正文拼进 shell。随后执行：

node "{CM_WORKFLOW_ROOT}/scripts/cm-refactor-entry.mjs" \
  --skill-dir "{CM_WORKFLOW_ROOT}/skills/cm-refactor" --project "{CODE_PROJECT}" \
  [--specs "{SPECS_DIR}"] --intent "{四类意图之一}" [--target-present]

没有 specs 的裸项目省略 --specs；有非空描述才传 --target-present。缺描述时入口返回 blocked / target_required。defect、behavior-change、gradual-adoption 分别只返回既有 $cm-fix、$cm-prd --change、普通改动出口并停止本流程，出口不构成执行授权；只有 structure-only 才继续校验项目/specs，ready / g0_feasibility 才进入 G0，且继续要求行为完全不变与 G0 人签核。返回的角色、日志和 Learning 均为 pending，执行/写入权限为 false；入口不读取项目正文、不跑判官、不调用 provider/browser/外部专家、不写日志/档案/RULEBOOK，也不替代后续轻量道或批量道。

JS 流程执行

只读分流返回 ready / g0_feasibility 后，按当前会话 JS 宿主启动同一轻量/批量控制器；批量、准备、写回与恢复协议在需要时读取。 JS 宿主负责日志与状态，不再手工重复写 run_start。恢复保留原配置、结果和审查轮次；未知调用先核对。批量默认串行、worker 只提议文本；真实宿主须保证 bakeoff 隔离和最终独立审查，不能用 header 自证。

不使用 JS 宿主时，两个路径校验通过后立即调用统一写入器记录 run_start；暂停/续跑沿用同一 .cm-run.json，完成收口人门后写 run_done。不得直接拼 JSON。

项目角色路由

从代码项目根解析 coder、tester、reviewer，并按 runtime/workflow-routing.md 写 decision/phase: route。角色配置只选择请求的实现、等价验证和独立审查适配器/模型别名；它不允许子代理提交 Git、改变规则手册、跳过判官或把 declared-adapter 当成已执行。resolver 返回非零或配置错误时立即 BLOCKED，不得进入 G0、扇出或修改代码；配置缺失时使用当前默认执行方式。 managed-adapter 按 runtime/model-efficiency.md 返回文本建议并自动记录真实 usage；行为基线、代码改动与独立审查仍保持本地。

角色调用按 runtime/model-efficiency.md 只传当前批次的行为基线、范围、diff、验证与审查证据；不得重复发送其他批次或完整历史。精简仅影响模型上下文与输出，不降低行为判官、独立审查或回归门禁。

结构调整专用闭环。前提:什么都没坏,行为一丝不变——设计依据见 docs/重构流程设计/(cm 小闭环纪律 × Anthropic 迁移方法论,核心教义:修规则,不修产物)。

分流门(先于一切,答错门就是错流程):

有缺陷要修 → $cm-fix
行为要变(哪怕"变得更合理")→ $cm-prd --change
渐进式采用(如 JS→TS 逐文件、加类型注解)→ 不用本命令,直接改
结构问题且行为保持 → 本命令

$cm-ai 全局规则同等生效：灾难级才暂停、多方案自主决策留痕、状态落盘（node 写 REFACTOR）、运行日志照记、审查按 runtime/review.md 执行。

续跑检测(先于 G0):{SPECS_DIR}/refactors/ 下存在未收口 slug(档案无收口节 / 运行日志该 slug 无 run_done 事件)→ 按磁盘状态定位续跑站点(RULEBOOK 版本、batch-log 完成集、队列缺口),G0 不重问、判官按 G0.5 重验后继续;无在制状态才走全新 G0。"队列=磁盘"的可恢复性必须有恢复入口才算数(对照系:cm:ai 有 tasks 断点、fix 有 slug 续跑,最长时的批量重构反而没有——本条补齐)。

G0: 可行性(人门)

动机量化:动机必须落到可测指标——行数超限 / 重复块 N 处 / 依赖方向违规 / 圈复杂度。"代码不优雅"不构成动机
认领待触发备忘:扫描 {SPECS_DIR}/LESSONS.md 的「待触发备忘」段,结构类条目(标记来源含"重构/拆分/看不惯")与本次目标相关的 → 列入范围并在输出注明认领;收口时销账(改状态为已认领,注档案路径)——备忘的回流出口(实跑教训:备忘只写不读,到期无人认领)
波及面:谁引用这块代码(有业务地图查 03/08,无地图 grep 调用方)
输出可行性摘要:范围清单 / 动机指标现值 / 波及面 / 预估轨道(轻量或批量)/ 预算可见乘法(批量道必填:文件数 × 单文件估耗 = 总预算,拍脑袋的总数不作数)。「不重构」是合法结论——收益盖不住风险就明说,命令到此收口
🛑 人签核后才进下一步(签核=踢下一阶段;阶段内不再停车)

G0.5: 判官自验证(无判官不开工)

判官 = 能平等裁决改前改后代码的机械标准,分两层:

基线层:存量测试全量跑绿并记录;无测试资产 → 先写现状快照测试(B3 同款,锁行为不判对错)
差分层:对将被重构的入口函数/接口,构造代表性输入集(含边界值),记录改前输出;harness 的环境解析照抄项目既有测试的做法(依赖怎么找、浏览器怎么起)——自造解析必踩环境坑(实跑:playwright 全局安装,裸 import 失败,照抄 smoke.mjs 的 npm root -g 解析才通)(实证方法:12 组输入逐字节对比,json-keeper 拆 core.js 验证过)

自验证(判官没被验证过,就不配当判官):

在原代码上跑 → 必须全绿
在故意破坏的代码上跑(手动种 ≥2 处行为变异,如改一个返回值、删一个分支)→ 必须变红;不红的判官修到红为止,变异恢复后再开工
判官报大面积失败时先怀疑判官(比较器空白处理/序列化陷阱是已知假阳性源),"一个把所有东西都判失败的裁判,通常是它坏了"

规模门(客观判据,不是感觉)

范围 ≤3 个文件且无跨模块搬迁且无文件增删 → 轻量道
其余 → 批量道
版本控制 = none → 禁入批量道(批量改动无 git 回滚是裸奔):只许轻量道并输出强警告,或建议先 git init

轻量道(五步,一次跑完)

重构:只动结构不动行为;禁止顺手修 bug(与 N3"禁止顺手重构"互为镜像)——发现缺陷 → 停下记录现象与位置进档案,收口后走 $cm-fix。夹带修复会毁掉差分判官:行为变了,是重构失手还是修复生效?无法归因
等价验证:基线全绿 + 差分逐项一致;任何行为差异 = 该步失败回滚——"差异其实更合理"也不例外,那是行为变更,走 prd --change 立项后再做
审查：执行下方「结构化审查门禁」；重点检查有无夹带行为变更、结构是否真的改善、差分覆盖是否充分
落盘:档案 {SPECS_DIR}/refactors/{YYYYMMDD}-{slug}.md(动机指标改前改后对照 / 等价验证方式与结果 / 发现未修缺陷清单);METRICS 行 Feature 列写 refactor;delivery=diff 不提交，branch/draft-mr 才 commit refactor: {一句话} (档案: refactors/xxx.md)
规则毕业:本次收敛出的持久约定(如"路由文件导出形态")→ 写进代码项目 .claude/rules/ 对应文件——一次重构的规则,变成项目的永久基因;项目无 .claude/rules/(未经 $cm-init)→ 降级记入 LESSONS [仅记忆] 并在档案注明,提示补跑 $cm-init 后迁入(实跑 DEV-003:diff-lens 未 init,毕业规则无处可去)

结构化审查门禁（两条轨道共用）

{slug} 先规范成跨平台安全的 ASCII kebab；令 REVIEW_FEATURE=refactor-{slug}、REVIEW_TASK=T-REFACTOR-{slug}。主执行者按真实 diff 和判官证据写 {SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-a{attempt}-handoff.json，先按完整 changed_files 运行 cm-task-gate.py hash-implementation --project-root {CODE_PROJECT} --file ... 并把返回的 implementation_sha256 写入 handoff，然后真跑：

python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n4 \
  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
  --feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}

独立审查投喂全部 diff + RULEBOOK（批量道）+ judge-report/diff-report 摘要；凭证严格落 {SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{attempt}.md 并绑定当前 handoff SHA。审查后必须真跑：

python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n5 \
  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
  --feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}

只有当前 attempt 的 verdict: approved 才能落盘/提交；changes_requested 生成 attempt 2 并复审，第 2 轮仍有阻断项写 blocked。旧凭证、空壳凭证或文件存在检查均不得放行。

第一轮要求补判官或测试时，审查返回 judgeRevision:{paths,reason}，只列启动时 testSetup.paths 内的文件；第二轮由宿主提议文本、控制器登记写入。先在启动时的业务原稿上重建答案并重做判官自验证，再与第二轮重构稿比较；详见判官修订与恢复。

批量道(五站 + 三条修上游回环)

教义:个别失败交给循环烧掉,重复失败控诉的是规则——修规则重新生成,不修产物。

站 1: 规则手册

建 {SPECS_DIR}/refactors/{slug}/RULEBOOK.md,meta 规则:两个 agent 会答得不同的问题,答案进手册(目标形态/命名映射/禁用模式/逃生舱标记 TODO(refactor):)
依赖图定批次顺序(文件粒度 + 模块粒度都查环)
手册在循环内只读:任何批内 diff 碰 RULEBOOK = 自动审查发现;修订排队给人,批间应用

站 2: 压力测试(人门)

双译对比(bakeoff):同 2-3 个最难的文件派两个隔离 agent——一个严格守 RULEBOOK,一个从不知道手册存在;第三个 agent 逐处 diff,每处差异裁决为「规则正确 / 规则缺失 / 规则错误」——差异清单就是规则修订清单(比"跑一遍看看"锐利:每个 diff 都是对某条规则的判决)
只要有一项裁决为规则缺失或规则错误，返回的手册在忽略行尾空白、换行符风格及首尾空行后就必须不同于对比前的手册，否则以 refactor_rule_revision_required 停机、不发布对比报告也不启动试点，修订是否解决问题仍由后续独立审查判断。
试点:按批量道管线原样跑通(含站 3 禁令与站 4 裁决);试点产物可弃,唯一留下的是规则修订
采样规模:批量 ≥10 单元 → 取 2-3 个最难文件;<10 单元 → 取 ⌈20%⌉ 且至少 1 个;偏离记偏差日志(实跑 DEV-001:5 单元取 1,规程数字对小批不成比例)
🛑 规则定稿人签核后才扇出

站 3: 批量执行

队列 = 磁盘:完成的客观定义是"该文件的重构产物存在且通过站 4"——可恢复、可并行、不靠记忆
配置禁令：开跑前读取 {CM_WORKFLOW_ROOT}/templates/refactor/cm-refactor-denies.json，将其约束注入每个 Codex 子代理：循环内禁 git 变更操作、禁重型测试命令。当前运行时无法保证这些边界时不扇出
扇出时按 runtime/orchestration.md 为 Codex 子代理注入对应工种 skill 与 RULEBOOK 摘录；子代理只做指定文件、不碰界外、不自行标记或提交
当前 Codex 运行时支持模型分层时，机械实现可用成本较低的模型，独立审查与规则修订保留高能力模型；不支持则使用当前模型，不将分层作为硬依赖
每个完成文件末尾带状态尾注 // REFACTOR STATUS: confidence={high|medium|low} todos={N};审查者对账实际 TODO(refactor) 数,尾注少报即为审查发现
提交在批次边界由主流程执行,循环 agent 不 commit

站 3.5: 装配(主流程职责,不派 agent)

按各单元 delta 清单执行编排层改写与加载登记类波及物(HTML script 注册 / 打包白名单 / 构建清单);agent 汇报的「需其他工种配合」在本站强制逐条消费,漏项即偏差记 DEV
装配产物(编排层 + 登记文件)与模块产物同等过站 4-5 判官链——装配是全程唯一无规则手册护航的手写高危区(实跑:全程唯一真 bug 出自装配期,root 缺绑定,站 5 拦截)

站 4: 机械裁决

裁判有价格,价格决定位置:typecheck/lint 便宜 → 进每文件循环;整体构建/重型测试贵 → 批末跑一次,错误清单按模块切片成下一批队列
同类错误第 3 次出现 = 规则 bug:停止修实例 → 修订 RULEBOOK(排队人批)→ 重新生成该批,不手工补丁(手工补丁让第 500 个文件和第 5 个文件长得不一样)
批间的一切规则驱动重生成/规范化变换视同新产物,必须重过站 4-5 判官链——机械变换是上下文盲的(实跑:挂载行统一变换把 root. 写进无 root 绑定的 IIFE,启动即挂,站 5 金样前的 smoke 拦截)

站 5: 行为等价

判官上场:基线全量绿 + 差分全组一致;差异 = 回滚该批重做
判官报异常先按 G0.5 自验证复查判官本身,再信判决

收口(同轻量道 3-5 + 追加)

先通过「结构化审查门禁」，再写档案(落 refactors/{slug}/ 目录,与 RULEBOOK 同处)、METRICS、规则毕业
偏差日志:跳过的环节、放宽的检查,一行一条记入档案 DEV-{序号} | 日期 | 跳过了什么 | 谁批准——没人记录的偏差就是没人批准的偏差
结构同步:重构天然改变文件结构——按 cm-doc-syncer 口径同步项目 README / CLAUDE.md 的目录与模块描述(调用 skill,不动其命令文件);收口清单含波及物核对:批内全部「需配合事项」逐条销账(实跑失误:U1 汇报的 README 同步在收口被漏,靠事后审计才发现)

收口人门(轻量道与批量道共用,全流程第三处签核)

🛑 双计数呈签核后本命令才算闭环:基线项全绿 + 差分组一致,连同档案、动机指标改前改后对照、预算对账(G0 预估 vs 实耗:agent 调用次数/时长,写入 METRICS 备注)一并打给人——不对账的预算永远是拍脑袋。与 G0、站 2 构成全流程恰好三处人门——门在阶段之间,签核=踢下一阶段,阶段内零停车(与 docs/重构流程设计/ 的图一致,图与实现不得漂移)。

运行日志必记事件(node 写 `REFACTOR`,格式同 cm:ai 全局规则)

node_enter:进入每道门/每站(G0、G0.5、规模门、各站、收口)
pause / resume:三处人门各一对(G0 签核、站 2 规则定稿、收口 done-gate)——人门无 pause 记录 = 门没停,审计可查
decision:规则修订采纳(修了哪条/为什么)、轨道选择、判官修复
task_start / task_done:轻量道按次;批量道按批次记,detail 必带数字(完成 N/总数 M · 差分通过率 · 动机指标现值)——单文件粒度不灌主日志,进明细层 batch-log(见下节)
error:判官假阳性排查、批次重生成(记明"第几次重复触发规则修订")、行为差异回滚
run_done:收口(双计数与 slug 写进 detail/data)

重构专属明细日志(事件层之下的第二层,轻量道不豁免只减薄)

为什么比 feature 开发厚:新开发的失败是"没做出来",看得见;重构的失败是"悄悄改了行为",事后归因全靠明细。事件级日志答得了"发生过什么",答不了"这个行为差异是哪个文件、哪版规则、哪次批次引入的"。

judge-report.md(refactors/{slug}/):判官档案——基线清单与结果、自验证变异清单(种了什么变异 / 抓到没有,漏抓的怎么修到抓到)、假阳性排查记录。判官的可信度证据,不是口头的"验证过了"
diff-report.md:差分明细——每组输入 / 改前输出 / 改后输出 / 结论,逐组落盘(不是一句"全部一致");出现差异时该组全文保留,回滚后补记处置
batch-log.jsonl(批量道):单文件粒度一行一条:{file, agent, model, rulebook_rev, diff_pass, todos, confidence, duration}——归因链的关键是 rulebook_rev:每个产物记录由哪版规则生成,行为差异出现时可精确定位"这批是坏规则的产物"而不是逐文件猜
RULEBOOK 修订史(手册内置表):版本 | 日期 | 触发实例(哪个失败) | 旧条文 → 新条文 | 裁决人——规则演进必须可追溯,否则"修规则不修产物"就成了无账本的改法
回滚记录:每次回滚在档案记一节(回滚了哪批 / 回到哪个 commit / 触发差异的输入组 / 归因结论),并与主日志 error 事件双写互指

落盘物清单(审计链)

落盘物	位置
运行日志 + 状态	`{SPECS_DIR}/运行日志.jsonl` 追加 · `.cm-status.json`(状态条自动显示 REFACTOR 进度)
明细层(判官/差分/批次/回滚)	`refactors/{slug}/` 下 judge-report.md · diff-report.md · batch-log.jsonl(批量道)
可行性摘要 + 档案	`{SPECS_DIR}/refactors/{日期}-{slug}.md`(批量道为同名目录)
RULEBOOK(批量道)	`refactors/{slug}/RULEBOOK.md`
审查凭证	`{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{N}.md`
度量	METRICS.md 追加行,Feature 列 `refactor`
毕业规则	代码项目 `.claude/rules/` 对应文件
备忘销账	LESSONS.md 待触发备忘状态更新

边界

不承接:缺陷(→ $cm-fix)、行为变更(→ $cm-prd --change)、架构级重设计(升级出口:交人经 $cm-prd 立项——重设计下规则手册变设计文档、试点对比失效,是另一种流程)
不触发 cm-qa-engineer:行为等价验证就是重构的 QA,行为没变就没有新 AC
没有 specs 目录的裸项目:档案落代码项目 docs/refactors/,凭证落 docs/refactors/.reviews/,METRICS 跳过(同 $cm-fix 惯例)

对上游方法论的三处有意改编(是取舍不是遗漏,放弃了什么留痕):

kit 的重设计模式(规则手册变设计文档)→ 整体分流给 $cm-prd 立项——cm 已有方案对抗审查链,不重复造
kit 的双对抗审查+第三方仲裁 → 用 cm 既有 N4 纪律(≤2 轮+分歧记录)——全框架审查纪律保持单一来源
kit 的缺口清单(gap inventory)→ 不设——那是跨语言迁移特有物(目标语言强制要求表),同语言行为保持重构由波及面清单承担残余职能

Files (cm-workflow)

references

js-batch.md 6.8 KB

# JS 批量、准备、写回与恢复

由可信当前会话准备配置，用户不必手写协议。本文是 js-host.md 的条件引用，不改变原业务规则。

## 配置增量

```json
{
  "testSetup": {"paths": ["test/all.mjs", "test/value-judge.mjs"]},
  "writebackPaths": ["AGENTS.md", "README.md", ".claude/rules/shape.md"],
  "batch": {
    "assemblyFiles": ["src/index.mjs"],
    "cheapCommands": [{"id": "syntax", "command": ["node", "--check", "{file}"]}],
    "maxPasses": 6
  }
}
```

三项都可省略。scope/testSetup/writeback 清单互不重叠；assemblyFiles 包含在 scope 内。
新增/跨模块/>3文件自动选批量；≤3文件的删除也须显式 batch。无 Git 基线禁止批量，不自动 init。
cheapCommands 的 `{file}` 只做 argv 替换、不经 shell；删除文件不跑语法检查。每批最多3–9次生成，默认6。
G0 展示业务、测试、规则/文档范围与命令；批量预算为文件数×单文件估耗，非实测 token。
testSetup 声明现有/待创建的判官资产；主流程准备文本后运行配置中的原基线与两次以上变异自验证。
首次准备漏检只修声明测试，最多三版；不能修生产行为使测试通过、换掉原变异或引入依赖。
第二轮补判官及旧审查追加登记见 [判官修订](js-host.md#第二轮判官修订)，只接受一次有界提案。
批量修订也先恢复启动时全部业务文件（含新增前不存在、删除前存在的文件）来验证新版判官；试点回退只恢复业务稿，批次日志继续追加。
writebackPaths 只允许项目 AGENTS、README、CLAUDE 和 `.claude/rules/*.md`，不授予 worker 写权限。

## 新增宿主回调

所有 files 项为 `{path,beforeDigest,content}`，digest 原样取请求，删除 content=null。回调只返回提案，不旁路写入/执行。

| kind / action | 实际宿主职责与 result |
| --- | --- |
| `refactor_prepare_tests` | `{files:[...]}`：只写声明的测试资产提案；保留现状（含缺陷）和既有环境解析。 |
| `refactor_batch / plan` | `{rulebook,units:[{id,files,dependsOn}],sample:[file],perFileEstimate,reason}`。只读检查文件及模块依赖，都编码到 dependsOn。JS 拒环并核对全清单；sample 按主 Skill 比例挑最难文件。 |
| `refactor_batch / bakeoff` | guided/blind 各用 fresh 隔离、无工具写权限作者，blind 不接手册或另一方历史。各回 `{files:[...],channelId}`。 |
| `refactor_batch / adjudicate` | 第三独立上下文回 `{channelId,rulebook,decisions:[{path,verdict:rule_correct或rule_missing或rule_wrong,reason}]}`，逐处判定差异，不自称作者也能独立。 |
| `refactor_batch / generate` | 单文件文本 worker 回 `{files:[...],needs:[{id,path,instruction}],summary}`。所有装配/加载登记/文档需求必须列出。非删除内容以语言合法注释携原 `// REFACTOR STATUS: confidence=high或medium或low todos=N`，JS 对账 TODO 数。 |
| `refactor_batch / assemble` | 主流程消费全部装配需求，回 `{files:[...],resolved:[needId]}`，不派单元 worker、不漏登记文件。 |
| `refactor_batch / diagnose` | 根据真实错误回 `{errorClass,reason}`。同类错误不靠文件名/行号另起类别，第三次修规则、人批准后重生成该批，不手补实例。 |
| `refactor_retrospective` | 主流程读取给定 doc-syncer Skill，回 `{learningApplication,learning:{status,candidates,reason},conventions:[{path,text,evidence}],documentation:[...],resolved:[needId],unfixedDefects:[],metricAfter}`；逐项核销结构文档 needs，不夹带 bug fix。 |

channelId 必须来自真实宿主。字符串不同不证明隔离；无法限制 worker 为文本/隔离上下文时不派发。
试点使用同一单元/廉价检查/装配/等价管线，失败修规则，成功丢弃产物；规则定稿人批准后串行生产。
每批廉价检查与批末基线/差分分开；差异回滚该批，保留输入和输出明细。规则修订保存版本/原因/裁决人，重生成再过判官。
规划只传清单/摘要，宿主按需读取；单元只传本文件，避免每次传整仓。

## Learning 与备忘

learning 沿用原格式：`{status:"no_new_lesson",candidates:[],reason:null}`，或
`{status:"lesson_candidate",candidates:[{classification:"structured"或"memory_only",trigger,action,evidence:[项目相对路径]}],reason:null}`。
最多3条、有真实证据，复用原合并器增量写 AGENTS 项目教训；无权限时阻断，不伪装无新增。
conventions 只追加已授权规则文件；项目没有规则目录时降级 LESSONS `[仅记忆]`，提示 cm-init 后迁移。
analysis.claimedMemos 使用原 LESSONS 的精确单行，主流程附已认领状态与档案路径；用户并发内容不覆盖。
AGENTS/规则/测试/结构文档均在最终 Review **之前**定稿，进入同一 changed_files/实现摘要。
外部 specs 的 LESSONS 原文和摘要进入审查包，收口再次核对；不另开完成通道。

## 恢复

新进程用同一配置/slug，发送 `{"requestId":"resume","operation":"resume"}`。读取原 execution.jsonl、RULEBOOK/批次，保留审查轮次。
已记录结果只复用、不再次问 G0/派发模型；到安全站点复查当前基线/差分。`status` 不写，漂移显示 correction_required 并保留历史阶段。
未知调用收到 `refactor_recover`：可信宿主查原调用/进程回执，不凭时间或文字 approved 推断。

- 已完成：`{decision:"completed",result:原形状,evidence:"实际核对依据"}`；host 结果为 `{value:原业务返回,durationMs:实测或null}`。
- 命令结果为 `{observed:原host-check结果,stdout,stderr}`，另需 `cleanupConfirmed:true` 证明原进程已清理。
- 确认未派发：`{decision:"not_started",evidence:"未派发证据"}` 才可执行原登记请求。
- 仍未知：`{decision:"unknown",evidence:"目前事实"}` 保持阻断；不得换 reviewer/新轮次绕过。

文件恢复只接受原值/本流程目标值；第三种内容保留。报告可从原记录重建，冲突不覆盖。
旧版缺 execution 记录的已有审查报 refactor_legacy_recovery_required，按旧证据人工处理，不自动导入/清除。
日志损坏、权限冲突、未知进程无法核对是合理阻断，不承诺任意中断都能无人恢复。

批量目录增加 RULEBOOK/修订史、batch-log、试点/差分/回滚明细与 dossier；execution 只辅助恢复，不替代原任务/日志/Review。
METRICS 保留八列，记录实测宿主调用/耗时；缺实际模型 token 遥测明确 unavailable。
本入口信封上限2MiB、业务返回1MiB；其他入口默认64KiB不变。大回复应减少无关文本或缩批，不截断后声称完整。
实际 provider、双端安装和 Git 交付分别需要授权；synthetic 本地夹具不证明真实模型判断与隔离。

js-host.md 9.5 KB

# cm-refactor 当前会话 JS 宿主

本入口统一实现原轻量/批量道，不改变意图分流、人签核、行为保持和独立审查要求。
轻量适用 1–3 个现有文件、不跨模块；批量、判官准备、写回及恢复见 [扩展协议](js-batch.md)。裸项目与 specs 项目均可。
宿主只能提出替换文本，JS 控制器执行本地文件写入、真实命令、归档与原 N4/N5 门禁。
这不是模型调用器；`runtime: codex|claude` 选择原角色配置，不证明真实模型已经调用。

## 准备与启动

单步调用可用 `node scripts/cm-refactor-drive.mjs --plan PLAN.json <start|resume|finish|status|cancel|prepare_judge_revision>`。
PLAN 写 `{ "config":"config.json", "answers":"answers" }`，路径相对 PLAN；答案按驾驶员 `--help` 与文件头准备。
驾驶员发送前核对配置、scope、内容文件、人工分析/审查/确认和恢复记录；缺项退出 2，不启动宿主。
基线、判官、变异及批量语法命令仍由宿主实际执行；结果不从答案文件读取。未知执行结果需原回执，驾驶员拒绝静态补写。

先完成主 Skill 的只读意图分流和路径准入。可信当前会话读取适用 AGENTS/调用方，核对原有
测试命令覆盖所有存量测试、判官覆盖目标入口及边界输入。只传启动前核实的 argv，不能执行模型
回复里临时出现的命令。需要新建测试资产时，由宿主在配置中声明 testSetup.paths 和执行命令，G0 批准后准备。

准备私有绝对路径 JSON 配置；以下示例的命令、替换和路径必须改为实际项目内容：

```json
{
  "skillDir": "/workflow/skills/cm-refactor",
  "project": "/project",
  "specs": null,
  "runtime": "codex",
  "target": "减少目标函数的重复分支，保持输入输出不变",
  "slug": "simplify-branch",
  "scope": ["src/value.mjs"],
  "crossModule": false,
  "baselineCommands": [{"id": "baseline", "command": ["node", "test/all.mjs"]}],
  "judgeCommand": ["node", "test/value-judge.mjs"],
  "mutations": [
    {"path": "src/value.mjs", "find": "x + 1", "replace": "x + 2"},
    {"path": "src/value.mjs", "find": "x < 0", "replace": "x < -5"}
  ],
  "logHome": "/private/cm-logs"
}
```

`logHome` 须在项目和 specs 外，是私有可重建镜像；有 specs 时其日志仍为权威。
业务 scope 不得含项目指令、凭证、specs 或归档；批量允许新增/删除普通文件。命令为可信本地执行，
不是沙箱：宿主须排除部署、网络、安装、Git 和不可恢复副作用，除非另有动作专项授权。
每个替换必须唯一命中且是可恢复的行为变异；判官自验证属于原 G0.5，不增加测试轮数。

```bash
node "{CM_WORKFLOW_ROOT}/scripts/cm-refactor-host.mjs" serve --config "{私有绝对配置路径}"
```

差分命令须以退出码 0 输出唯一 JSON：`{"cases":[{"id":"unique","input":0,"output":1}]}`。
输入与顺序在各次运行保持一致，判官不写源码；原输出为绿，两次变异须得到可比较且不同的输出。
JS 每次变异后恢复自己写入的精确内容；检测到并发修改时保留现场并阻断，不用 Git 重置。

## 当前会话接线

保持同一个 JSONL 进程。收到 `host_ready` 后发 `{"requestId":"start","operation":"start"}`。
`host_request` 的回复沿用原桥协议：`type:host_result`，原样回传 `sessionId/callId/requestDigest`，
业务返回值置于 `result`。不要把结果写到 stdout 之外的伪协议文件。

| kind | 当前宿主实际动作与 result |
| --- | --- |
| `refactor_analyze` | 只读分析调用方、量化收益及相关 LESSONS 备忘。返回 `{decision:proceed或no_refactor,metric:{name,before,unit},impact:[],claimedMemos:[],reason}`；不得隐藏已认领备忘。 |
| `refactor_confirm` | 向当前用户展示 payload 的范围、命令/变异或收口证据，取得本次明确决定，返回 `{decision:approved或rejected}`；不得因以前“继续”而伪造批准。 |
| `refactor_apply` | 返回 `{files:[{path,beforeDigest,content}],summary,metricAfter,unfixedDefects:[],conventions:[],learningApplication,learningRetrospective}`。digest 取请求值；只提供文本，不写文件、不运行命令。无新教训时 retrospective 为 `no_new_lesson`，新增则使用扩展协议的 learning 结构。 |
| `refactor_review` | 依 `runtime/review.md` 使用真正独立通道，传当前完整 handoff、差分/自验证报告、范围前后内容及命令。返回 `{markdown}`，保留原头部、精确 handoff SHA、attempt=round 和 scope。无法取得独立审查则停止；不得自写 approved、复用旧批准或发起未授权 provider。 |
| `refactor_revise_tests` | 仅第一轮审查明确要求补测试时调用。读取 `findings` 和 `assets`，返回 `{files:[{path,beforeDigest,content}]}`；只改本次列出的测试文件，摘要沿用请求值。不得直接写盘、运行命令或改业务文件。 |

审查 round 1 的 changes_requested 会在同一配置内修订一次；round 2 仍有阻塞则停止。
模型质量、行为覆盖充分性、角色执行来源与审查独立性由真实宿主保证，结构化 header 本身不能证明。
返回 `awaiting_finish` 后发送 `{"requestId":"finish","operation":"finish"}`，控制器再次核对原 N5、
询问当前用户收口决定并归档。收口拒绝只停在原位置，不重做修改或审查。
`status` 只读状态；`resume` 同配置接回原记录；`cancel` 中止在途工作；退出用 `{type:host_close,sessionId}`。

## 第二轮判官修订

启动前把允许维护的现有或待建测试文件逐个列入 `testSetup.paths`，并在 G0 展示；它与业务
`scope` 必须分离。第一轮审查若要求改这些文件，返回如下结果，正文也须说明对应发现：

```json
{"markdown":"带完整头部的 changes_requested 审查正文","judgeRevision":{"paths":["test/value-judge.mjs"],"reason":"补齐遗漏的边界输入"}}
```

`paths` 必须非空、不重复且全部属于原配置的 `testSetup.paths`，`reason` 必须非空。
未声明的文件不能临时加入；不能修改配置、命令、变异清单，或换 slug 重置轮次。
没有此字段的审查默认沿用原业务修订路径；可信宿主可在交回第一轮结果前整理该声明，
已经归档的纯文字发现则走下方追加登记。批准结果及第二轮审查均不能启动测试修订。

控制器只接受一次有实际变化的文本提案，沿用文件摘要、路径保护、原子写入与并发检查。
提案和原审查绑定另存 `a2-judge-revision.md`；每次写入追加日志，旧报告、回执不覆盖。
随后临时恢复**启动时记录的业务原稿**（包括启动前已有改动），用新版测试跑基线、采集答案，
并重新执行原变异清单自验证，另存 `a2-judge-1-report.md`。不能只对重构稿生成预期答案。

自验证通过后恢复待修的重构稿，再执行第二轮业务修改和行为比较；轻量、批量均走此顺序。
测试差分、新旧报告一并进入第二轮交接与独立审查。新判官暴露的行为变化必须在原业务范围
内纠正，比较不等则阻断。原稿基线失败或判官漏检变异也阻断，不增加测试提案或审查轮次。

中断后保持原配置执行 `resume`；控制器按记录接续测试写入、原稿切换、自验证和候选稿恢复。
未知宿主或命令结果须按原恢复协议核对并确认资源清理，不能自动重跑或把当前盘面当新原稿。
不要手工恢复临时原稿或覆盖测试文件；外部写入、路径或权限变化仍按原守卫阻断。

### 旧审查的追加登记

旧运行已归档的第一轮审查要求补测试，却没有 `judgeRevision` 字段时，可信宿主核对原发现后发送：

```json
{"requestId":"prepare-judge","operation":"prepare_judge_revision","judgeRevision":{"paths":["test/value-judge.mjs"],"reason":"处置第一轮已记录的边界测试缺口"}}
```

仅接受原第一轮合法 `changes_requested`，且第二轮尚未受控写入、执行验证或派发审查。
已缓存但被范围检查拒绝的 `a2/apply` 文本提案可以保留；在途未知调用须先核对，不能借此重跑。
登记绑定原审查文件、宿主结果以及被取代提案的摘要，返回 `judge_revision_prepared`，随后用原配置 `resume`。

原审查、旧提案和日志字节不变；新业务提案使用 `a2-after-judge-revision/apply`，attempt 仍为 2。
登记仅一次，相同请求幂等，不能更换范围或原因；已声明新版修订或已消费第二轮的运行拒绝登记。
这不是任意阶段回退、换配置或增加审查轮次的入口。

## 结果与验收边界

规格项目的判官报告在 `specs/refactors/<slug>/`，原审查在 `specs/.reviews/`，档案为
`specs/refactors/YYYYMMDD-<slug>.md`，追加原八列 METRICS，日志与 `.cm-status.json` 使用 REFACTOR。
裸项目归档于 `docs/refactors/`，不创建 METRICS/specs 状态。交付方式仅 diff，不自动提交。
行为回归阻断审查并尝试恢复本流程精确写入；并发冲突或未知副作用保留现场，需人工处理。
`done` 只说明本次 refactor/diff 流程完成，`completionAuthorized:false` 不授予其他 tasks 的完成权。

批量、跨进程恢复、判官准备、备忘和规则/Learning 已接同一控制器，不能删证据/换 slug 重置轮次。
源码/本地 synthetic 夹具不等于真实宿主隔离、模型判断、安装或业务验收；这些须单列实际证据。
branch/draft-MR 的 Git/远程动作沿仓库原交付流程另行授权，本入口不假称已提交。

SKILL.md 19.6 KB

---
name: cm-refactor
description: 用户明确要求“只整理结构，不改变行为”时使用。执行边界分流、行为判官、分批重构和独立审查；缺陷修复转交 cm-fix，新增或变化的业务行为转交 cm-prd。
---

# cm-refactor — 重构闭环（行为保持）

执行前读取 `../../runtime/project-context.md`、`../../runtime/orchestration.md`、
`../../runtime/review.md`、`../../runtime/model-efficiency.md` 与
`../../runtime/logging.md`。Codex 入口为 `$cm-refactor`；Claude Code 跨平台入口为
`/cm-refactor`，macOS/Linux 另有历史别名 `/cm:refactor`。

用户明确要求外部专家，或为本次重构开启 AUTO 时，按
`../../runtime/external-expert.md` 执行 `../external-expert/SKILL.md` 的任务路由。
重构写入、行为判官与审查保持 LOCAL；复杂方案比较可 CONSULT，权威事实可 VERIFY。
外部结果只进入候选方案和风险清单，不得修改行为基线、代跑判官或满足独立审查。

**用法**:`$cm-refactor {specs路径} {代码项目路径} 重构目标描述(哪块代码/为什么难维护)`

## JS 只读分流

在读取项目内容、解析角色、写 `run_start`、建立行为基线或修改代码前，先确认本轮有非空目标描述，
并按下方“分流门”将意图归为 `defect`、`behavior-change`、`gradual-adoption` 或
`structure-only`；不要把描述正文拼进 shell。随后执行：

```bash
node "{CM_WORKFLOW_ROOT}/scripts/cm-refactor-entry.mjs" \
  --skill-dir "{CM_WORKFLOW_ROOT}/skills/cm-refactor" --project "{CODE_PROJECT}" \
  [--specs "{SPECS_DIR}"] --intent "{四类意图之一}" [--target-present]
```

没有 specs 的裸项目省略 `--specs`；有非空描述才传 `--target-present`。缺描述时入口返回
`blocked / target_required`。`defect`、`behavior-change`、`gradual-adoption` 分别只返回既有
`$cm-fix`、`$cm-prd --change`、普通改动出口并停止本流程，出口不构成执行授权；只有
`structure-only` 才继续校验项目/specs，`ready / g0_feasibility` 才进入 G0，且继续要求行为完全不变
与 G0 人签核。返回的角色、日志和
Learning 均为 `pending`，执行/写入权限为 false；入口不读取项目正文、不跑判官、不调用
provider/browser/外部专家、不写日志/档案/RULEBOOK，也不替代后续轻量道或批量道。

### JS 流程执行

只读分流返回 `ready / g0_feasibility` 后，按 [当前会话 JS 宿主](references/js-host.md)
启动同一轻量/批量控制器；[批量、准备、写回与恢复协议](references/js-batch.md)在需要时读取。
JS 宿主负责日志与状态，不再手工重复写 `run_start`。恢复保留原配置、结果和审查轮次；未知调用先核对。
批量默认串行、worker 只提议文本；真实宿主须保证 bakeoff 隔离和最终独立审查，不能用 header 自证。

不使用 JS 宿主时，两个路径校验通过后立即调用统一写入器记录 `run_start`；暂停/续跑沿用同一
`.cm-run.json`，完成收口人门后写 `run_done`。不得直接拼 JSON。

## 项目角色路由

从代码项目根解析 `coder`、`tester`、`reviewer`，并按
`runtime/workflow-routing.md` 写 `decision`/`phase: route`。角色配置只选择请求的
实现、等价验证和独立审查适配器/模型别名；它不允许子代理提交 Git、改变规则手册、
跳过判官或把 `declared-adapter` 当成已执行。resolver 返回非零或配置错误时立即
`BLOCKED`，不得进入 G0、扇出或修改代码；配置缺失时使用当前默认执行方式。
`managed-adapter` 按 `runtime/model-efficiency.md` 返回文本建议并自动记录真实 usage；
行为基线、代码改动与独立审查仍保持本地。

角色调用按 `runtime/model-efficiency.md` 只传当前批次的行为基线、范围、diff、验证与
审查证据；不得重复发送其他批次或完整历史。精简仅影响模型上下文与输出，不降低
行为判官、独立审查或回归门禁。

结构调整专用闭环。**前提:什么都没坏,行为一丝不变**——设计依据见 `docs/重构流程设计/`(cm 小闭环纪律 × Anthropic 迁移方法论,核心教义:修规则,不修产物)。

**分流门(先于一切,答错门就是错流程)**:

- 有缺陷要修 → `$cm-fix`
- 行为要变(哪怕"变得更合理")→ `$cm-prd --change`
- 渐进式采用(如 JS→TS 逐文件、加类型注解)→ 不用本命令,直接改
- 结构问题且行为保持 → 本命令

**$cm-ai 全局规则同等生效**：灾难级才暂停、多方案自主决策留痕、状态落盘（node 写 `REFACTOR`）、运行日志照记、审查按 `runtime/review.md` 执行。

**续跑检测(先于 G0)**:`{SPECS_DIR}/refactors/` 下存在未收口 slug(档案无收口节 / 运行日志该 slug 无 `run_done` 事件)→ **按磁盘状态定位续跑站点**(RULEBOOK 版本、batch-log 完成集、队列缺口),G0 不重问、判官按 G0.5 重验后继续;无在制状态才走全新 G0。"队列=磁盘"的可恢复性必须有恢复入口才算数(对照系:cm:ai 有 tasks 断点、fix 有 slug 续跑,最长时的批量重构反而没有——本条补齐)。

## G0: 可行性(人门)

1. **动机量化**:动机必须落到可测指标——行数超限 / 重复块 N 处 / 依赖方向违规 / 圈复杂度。"代码不优雅"不构成动机
2. **认领待触发备忘**:扫描 `{SPECS_DIR}/LESSONS.md` 的「待触发备忘」段,结构类条目(标记来源含"重构/拆分/看不惯")与本次目标相关的 → 列入范围并在输出注明认领;收口时销账(改状态为已认领,注档案路径)——备忘的回流出口(实跑教训:备忘只写不读,到期无人认领)
3. 波及面:谁引用这块代码(有业务地图查 03/08,无地图 grep 调用方)
4. 输出可行性摘要:范围清单 / 动机指标现值 / 波及面 / 预估轨道(轻量或批量)/ **预算可见乘法**(批量道必填:文件数 × 单文件估耗 = 总预算,拍脑袋的总数不作数)。**「不重构」是合法结论**——收益盖不住风险就明说,命令到此收口
5. **🛑 人签核后才进下一步**(签核=踢下一阶段;阶段内不再停车)

## G0.5: 判官自验证(无判官不开工)

判官 = 能平等裁决改前改后代码的机械标准,分两层:

- **基线层**:存量测试全量跑绿并记录;无测试资产 → 先写现状快照测试(B3 同款,锁行为不判对错)
- **差分层**:对将被重构的入口函数/接口,构造代表性输入集(含边界值),记录改前输出;**harness 的环境解析照抄项目既有测试的做法**(依赖怎么找、浏览器怎么起)——自造解析必踩环境坑(实跑:playwright 全局安装,裸 import 失败,照抄 smoke.mjs 的 npm root -g 解析才通)(实证方法:12 组输入逐字节对比,json-keeper 拆 core.js 验证过)

**自验证(判官没被验证过,就不配当判官)**:

- 在**原代码**上跑 → 必须全绿
- 在**故意破坏的代码**上跑(手动种 ≥2 处行为变异,如改一个返回值、删一个分支)→ 必须变红;**不红的判官修到红为止**,变异恢复后再开工
- 判官报大面积失败时先怀疑判官(比较器空白处理/序列化陷阱是已知假阳性源),"一个把所有东西都判失败的裁判,通常是它坏了"

## 规模门(客观判据,不是感觉)

- 范围 ≤3 个文件 且 无跨模块搬迁 且 无文件增删 → **轻量道**
- 其余 → **批量道**
- **版本控制 = none → 禁入批量道**(批量改动无 git 回滚是裸奔):只许轻量道并输出强警告,或建议先 git init

## 轻量道(五步,一次跑完)

1. **重构**:只动结构不动行为;**禁止顺手修 bug**(与 N3"禁止顺手重构"互为镜像)——发现缺陷 → 停下记录现象与位置进档案,收口后走 `$cm-fix`。夹带修复会毁掉差分判官:行为变了,是重构失手还是修复生效?无法归因
2. **等价验证**:基线全绿 + 差分逐项一致;**任何行为差异 = 该步失败回滚**——"差异其实更合理"也不例外,那是行为变更,走 prd --change 立项后再做
3. **审查**：执行下方「结构化审查门禁」；重点检查有无夹带行为变更、结构是否真的改善、差分覆盖是否充分
4. **落盘**:档案 `{SPECS_DIR}/refactors/{YYYYMMDD}-{slug}.md`(动机指标改前改后对照 / 等价验证方式与结果 / 发现未修缺陷清单);METRICS 行 Feature 列写 `refactor`;delivery=diff 不提交，branch/draft-mr 才 commit `refactor: {一句话} (档案: refactors/xxx.md)`
5. **规则毕业**:本次收敛出的持久约定(如"路由文件导出形态")→ 写进代码项目 `.claude/rules/` 对应文件——一次重构的规则,变成项目的永久基因;**项目无 `.claude/rules/`(未经 $cm-init)→ 降级记入 LESSONS `[仅记忆]` 并在档案注明,提示补跑 $cm-init 后迁入**(实跑 DEV-003:diff-lens 未 init,毕业规则无处可去)

### 结构化审查门禁（两条轨道共用）

`{slug}` 先规范成跨平台安全的 ASCII kebab；令
`REVIEW_FEATURE=refactor-{slug}`、`REVIEW_TASK=T-REFACTOR-{slug}`。主执行者按真实
diff 和判官证据写
`{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-a{attempt}-handoff.json`，
先按完整 `changed_files` 运行
`cm-task-gate.py hash-implementation --project-root {CODE_PROJECT} --file ...` 并把返回的
`implementation_sha256` 写入 handoff，然后真跑：

```bash
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n4 \
  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
  --feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}
```

独立审查投喂全部 diff + RULEBOOK（批量道）+ judge-report/diff-report 摘要；凭证严格落
`{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{attempt}.md` 并绑定当前
handoff SHA。审查后必须真跑：

```bash
python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n5 \
  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
  --feature refactor-{slug} --task T-REFACTOR-{slug} --project-root {CODE_PROJECT}
```

只有当前 attempt 的 `verdict: approved` 才能落盘/提交；`changes_requested` 生成
attempt 2 并复审，第 2 轮仍有阻断项写 `blocked`。旧凭证、空壳凭证或文件存在检查
均不得放行。

第一轮要求补判官或测试时，审查返回 `judgeRevision:{paths,reason}`，只列启动时
`testSetup.paths` 内的文件；第二轮由宿主提议文本、控制器登记写入。先在启动时的业务原稿上
重建答案并重做判官自验证，再与第二轮重构稿比较；详见 [判官修订与恢复](references/js-host.md#第二轮判官修订)。

## 批量道(五站 + 三条修上游回环)

> 教义:个别失败交给循环烧掉,**重复失败控诉的是规则**——修规则重新生成,不修产物。

### 站 1: 规则手册

- 建 `{SPECS_DIR}/refactors/{slug}/RULEBOOK.md`,meta 规则:**两个 agent 会答得不同的问题,答案进手册**(目标形态/命名映射/禁用模式/逃生舱标记 `TODO(refactor):`)
- 依赖图定批次顺序(文件粒度 + 模块粒度都查环)
- **手册在循环内只读**:任何批内 diff 碰 RULEBOOK = 自动审查发现;修订排队给人,批间应用

### 站 2: 压力测试(人门)

- **双译对比(bakeoff)**:同 2-3 个最难的文件派两个隔离 agent——一个严格守 RULEBOOK,一个**从不知道手册存在**;第三个 agent 逐处 diff,每处差异裁决为「规则正确 / 规则缺失 / 规则错误」——差异清单就是规则修订清单(比"跑一遍看看"锐利:每个 diff 都是对某条规则的判决)
- 只要有一项裁决为规则缺失或规则错误，返回的手册在忽略行尾空白、换行符风格及首尾空行后就必须不同于对比前的手册，否则以 `refactor_rule_revision_required` 停机、不发布对比报告也不启动试点，修订是否解决问题仍由后续独立审查判断。
- 试点:按批量道管线原样跑通(含站 3 禁令与站 4 裁决);**试点产物可弃,唯一留下的是规则修订**
- 采样规模:批量 ≥10 单元 → 取 2-3 个最难文件;<10 单元 → 取 ⌈20%⌉ 且至少 1 个;偏离记偏差日志(实跑 DEV-001:5 单元取 1,规程数字对小批不成比例)
- 🛑 规则定稿人签核后才扇出

### 站 3: 批量执行

- **队列 = 磁盘**:完成的客观定义是"该文件的重构产物存在且通过站 4"——可恢复、可并行、不靠记忆
- **配置禁令**：开跑前读取 `{CM_WORKFLOW_ROOT}/templates/refactor/cm-refactor-denies.json`，将其约束注入每个 Codex 子代理：循环内禁 git 变更操作、禁重型测试命令。当前运行时无法保证这些边界时**不扇出**
- 扇出时按 `runtime/orchestration.md` 为 Codex 子代理注入对应工种 skill 与 RULEBOOK 摘录；子代理只做指定文件、不碰界外、不自行标记或提交
- 当前 Codex 运行时支持模型分层时，机械实现可用成本较低的模型，独立审查与规则修订保留高能力模型；不支持则使用当前模型，不将分层作为硬依赖
- 每个完成文件末尾带状态尾注 `// REFACTOR STATUS: confidence={high|medium|low} todos={N}`;审查者对账实际 `TODO(refactor)` 数,**尾注少报即为审查发现**
- 提交在批次边界由主流程执行,循环 agent 不 commit

### 站 3.5: 装配(主流程职责,不派 agent)

- 按各单元 delta 清单执行**编排层改写**与**加载登记类波及物**(HTML script 注册 / 打包白名单 / 构建清单);agent 汇报的「需其他工种配合」在本站**强制逐条消费**,漏项即偏差记 DEV
- 装配产物(编排层 + 登记文件)与模块产物**同等过站 4-5 判官链**——装配是全程唯一无规则手册护航的手写高危区(实跑:全程唯一真 bug 出自装配期,root 缺绑定,站 5 拦截)

### 站 4: 机械裁决

- **裁判有价格,价格决定位置**:typecheck/lint 便宜 → 进每文件循环;整体构建/重型测试贵 → 批末跑一次,错误清单按模块切片成下一批队列
- **同类错误第 3 次出现 = 规则 bug**:停止修实例 → 修订 RULEBOOK(排队人批)→ **重新生成该批**,不手工补丁(手工补丁让第 500 个文件和第 5 个文件长得不一样)
- **批间的一切规则驱动重生成/规范化变换视同新产物,必须重过站 4-5 判官链**——机械变换是上下文盲的(实跑:挂载行统一变换把 `root.` 写进无 root 绑定的 IIFE,启动即挂,站 5 金样前的 smoke 拦截)

### 站 5: 行为等价

- 判官上场:基线全量绿 + 差分全组一致;差异 = 回滚该批重做
- 判官报异常先按 G0.5 自验证复查判官本身,再信判决

### 收口(同轻量道 3-5 + 追加)

- 先通过「结构化审查门禁」，再写档案(落 `refactors/{slug}/` 目录,与 RULEBOOK 同处)、METRICS、规则毕业
- **偏差日志**:跳过的环节、放宽的检查,一行一条记入档案 `DEV-{序号} | 日期 | 跳过了什么 | 谁批准`——没人记录的偏差就是没人批准的偏差
- **结构同步**:重构天然改变文件结构——按 cm-doc-syncer 口径同步项目 README / CLAUDE.md 的目录与模块描述(调用 skill,不动其命令文件);收口清单含**波及物核对**:批内全部「需配合事项」逐条销账(实跑失误:U1 汇报的 README 同步在收口被漏,靠事后审计才发现)

## 收口人门(轻量道与批量道共用,全流程第三处签核)

🛑 **双计数呈签核后本命令才算闭环**:基线 {N} 项全绿 + 差分 {M} 组一致,连同档案、动机指标改前改后对照、**预算对账**(G0 预估 vs 实耗:agent 调用次数/时长,写入 METRICS 备注)一并打给人——不对账的预算永远是拍脑袋。与 G0、站 2 构成全流程恰好三处人门——门在阶段之间,签核=踢下一阶段,阶段内零停车(与 `docs/重构流程设计/` 的图一致,图与实现不得漂移)。

## 运行日志必记事件(node 写 `REFACTOR`,格式同 cm:ai 全局规则)

- `node_enter`:进入每道门/每站(G0、G0.5、规模门、各站、收口)
- `pause` / `resume`:**三处人门各一对**(G0 签核、站 2 规则定稿、收口 done-gate)——人门无 pause 记录 = 门没停,审计可查
- `decision`:规则修订采纳(修了哪条/为什么)、轨道选择、判官修复
- `task_start` / `task_done`:轻量道按次;批量道按**批次**记,detail 必带数字(完成 N/总数 M · 差分通过率 · 动机指标现值)——单文件粒度不灌主日志,进明细层 batch-log(见下节)
- `error`:判官假阳性排查、批次重生成(记明"第几次重复触发规则修订")、行为差异回滚
- `run_done`:收口(双计数与 slug 写进 detail/data)

## 重构专属明细日志(事件层之下的第二层,轻量道不豁免只减薄)

> 为什么比 feature 开发厚:新开发的失败是"没做出来",看得见;重构的失败是"**悄悄改了行为**",事后归因全靠明细。事件级日志答得了"发生过什么",答不了"这个行为差异是哪个文件、哪版规则、哪次批次引入的"。

- **judge-report.md**(`refactors/{slug}/`):判官档案——基线清单与结果、自验证变异清单(**种了什么变异 / 抓到没有**,漏抓的怎么修到抓到)、假阳性排查记录。判官的可信度证据,不是口头的"验证过了"
- **diff-report.md**:差分明细——每组输入 / 改前输出 / 改后输出 / 结论,逐组落盘(不是一句"全部一致");出现差异时该组全文保留,回滚后补记处置
- **batch-log.jsonl**(批量道):单文件粒度一行一条:`{file, agent, model, rulebook_rev, diff_pass, todos, confidence, duration}`——**归因链的关键是 `rulebook_rev`**:每个产物记录由哪版规则生成,行为差异出现时可精确定位"这批是坏规则的产物"而不是逐文件猜
- **RULEBOOK 修订史**(手册内置表):`版本 | 日期 | 触发实例(哪个失败) | 旧条文 → 新条文 | 裁决人`——规则演进必须可追溯,否则"修规则不修产物"就成了无账本的改法
- **回滚记录**:每次回滚在档案记一节(回滚了哪批 / 回到哪个 commit / 触发差异的输入组 / 归因结论),并与主日志 `error` 事件双写互指

## 落盘物清单(审计链)

| 落盘物 | 位置 |
| ---- | ---- |
| 运行日志 + 状态 | `{SPECS_DIR}/运行日志.jsonl` 追加 · `.cm-status.json`(状态条自动显示 REFACTOR 进度) |
| 明细层(判官/差分/批次/回滚) | `refactors/{slug}/` 下 judge-report.md · diff-report.md · batch-log.jsonl(批量道) |
| 可行性摘要 + 档案 | `{SPECS_DIR}/refactors/{日期}-{slug}.md`(批量道为同名目录) |
| RULEBOOK(批量道) | `refactors/{slug}/RULEBOOK.md` |
| 审查凭证 | `{SPECS_DIR}/.reviews/refactor-{slug}-T-REFACTOR-{slug}-r{N}.md` |
| 度量 | METRICS.md 追加行,Feature 列 `refactor` |
| 毕业规则 | 代码项目 `.claude/rules/` 对应文件 |
| 备忘销账 | LESSONS.md 待触发备忘状态更新 |

## 边界

- **不承接**:缺陷(→ $cm-fix)、行为变更(→ $cm-prd --change)、架构级重设计(升级出口:交人经 $cm-prd 立项——重设计下规则手册变设计文档、试点对比失效,是另一种流程)
- **不触发 cm-qa-engineer**:行为等价验证就是重构的 QA,行为没变就没有新 AC
- 没有 specs 目录的裸项目:档案落代码项目 `docs/refactors/`,凭证落 `docs/refactors/.reviews/`,METRICS 跳过(同 $cm-fix 惯例)

**对上游方法论的三处有意改编**(是取舍不是遗漏,放弃了什么留痕):

- kit 的重设计模式(规则手册变设计文档)→ 整体分流给 `$cm-prd` 立项——cm 已有方案对抗审查链,不重复造
- kit 的双对抗审查+第三方仲裁 → 用 cm 既有 N4 纪律(≤2 轮+分歧记录)——全框架审查纪律保持单一来源
- kit 的缺口清单(gap inventory)→ 不设——那是跨语言迁移特有物(目标语言强制要求表),同语言行为保持重构由波及面清单承担残余职能