Cm fix

cm-fix — 缺陷修复小闭环

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

用法：$cm-fix {specs路径} {代码项目路径} 缺陷描述（现象/报错/截图均可）

修 bug 专用的轻量闭环——不走 N1–N8 全链（那是 feature 流程），也不许脱离工作流裸改（裸改没防护网没审查，修一个坏三个）。

多缺陷输入：先对全部缺陷做第 1-2 步（复现+定位），按根因聚类——同根缺陷合并为一次修复（多个失败测试、一次改动、档案互链），修复顺序按严重度排,不按输入顺序。不聚类的代价：三个现象一个根因跑三个闭环,且第一个修复落地后,后两个的复现步骤可能已失效（第 1 步卡死）。

转交进场（消费上游落盘物,不改上游流程）：缺陷描述可附上游档案引用——$cm-refactor 档案的未修缺陷清单、N6 业务走查报告的偏差项、观测闭环的半份档案（按 slug 在 fixes/ 检索）。带引用进场的缺陷,第 1 步采信上游已有证据（位置/现象/日志原文）,仍须实际复现一次核实,但不从零摸排。

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

闭环七步（每个缺陷）

1. 复现（不能复现的 bug 不许修）

• 按描述实际操作/运行一次，拿到失败证据（报错原文、错误截图、错误返回值）;证据要用严格裁判——宽容裁判会把坏产物蒙混成功（实跑:补丁类缺陷 GNU patch 的 fuzz 容错险些吞掉复现,换 git apply --check 才拿到硬证据）
• 复现不了 → 不猜着修，走观测闭环（偶现 bug 专用，两段式）： ① 在可疑路径加观测点（日志/埋点——观测点本身按最小改动+审查纪律入库，观测点不是修复尝试） ② 缺陷档案先落半份，状态记 观测中，写清"等什么证据（哪个日志出现什么内容）" ③ 本次命令正常收口退出，不挂着等——运行日志记 done,detail 写「观测中:等{什么证据}」;状态文件 state 复位,不留悬挂的 running ④ 证据到手后再次运行 $cm-fix 附上证据，按 slug 定位 fixes/ 下的半份档案,从第 2 步定位续跑,档案续写、状态改 修复中,运行日志记 resume(detail 注证据摘要) ——"我改了点东西你再试试"依然被禁止

2. 定位（先找根因，不是找改哪行能让现象消失）

• 有业务地图（docs/codebase-context/）→ 先查 07 业务线路定位所在链路，08 修改影响映射表查波及面
• 无地图 → 从失败点向上追调用链，找到根因层（现象在 UI，根因可能在数据层）
• 输出一句话根因结论 + 波及面清单（本次修改会牵连哪些模块）——写进缺陷档案（第 7 步）

2.5 根因与修法对抗确认（条件触发；根因错误是本流程最贵的错误,必须在防护网之前拦）

任一客观条件命中才触发(简单缺陷零负担,判断依据同"门槛是客观项不是判断题"):波及面 ≥3 个模块 / 根因层与现象层不同层 / 观测闭环续跑的缺陷 / 拟走升级出口。

• 把根因结论 + 复现证据 + 波及面清单 + **拟采用修法（含放弃的备选）**交给新上下文的独立审查者，提示词要义：「假设这个根因判断是错的，找出更深层的解释；再审修法：治本还是治症？有没有更小的改动？会不会引入新耦合？」。通道与降级规则同 N4
• 仅 1 轮:推翻 → 回第 2 步重定位;分歧 → 交人裁决;通过 → 进第 3 步
• 凭证落 {SPECS_DIR}/.reviews/fix-{slug}-cause-r1.md——命名带 cause 是有意的:不落入第 5 步 fix-{slug}-r*.md 的匹配域,两个卡点各自独立,根因凭证不会误满足 diff 审查卡点

3. 防护网（先让 bug 有测试，再修）

• 写一个能复现此 bug 的失败测试（红）——它是"修好了"的客观定义，也是永久回归资产;红的原始输出落进档案(第 5 步审查要核对红证据,从未红过的测试转绿是空话)
• 项目有存量测试 → 先跑一遍记录基线（修完对照，防止修 A 坏 B）
• 写不了自动化测试的形态（如纯视觉）→ 截图/录屏留"修前"证据

4. 修复（最小改动）

• 只改根因层，禁止顺手重构（N3 同款纪律：看不惯的代码记 LESSONS 待触发备忘，事后走 $cm-refactor，不在修 bug 时动）
• 修法有多个方案 → 自主决策选最优，decision 事件留痕
• 升级出口：定位发现是设计缺陷/需要跨模块大改 → 停止硬修，报告根因并建议走 $cm-prd --change 变更模式立项——bug 命令不承接架构手术。已建资产不弃:第 3 步的失败测试保留入库（它是缺陷的客观复现,新方案转绿即验收）,档案状态记 升级立项,注明测试路径供立项后的流程直接接手

5. 审查（独立审查同 N4）

• 失败测试转绿 + 存量基线不退化后，按 runtime/review.md 审查本缺陷 diff（重点：根因是否真被修掉、有无只治症状、波及面有无遗漏）
• 防护网测试本身是审查对象(实测最大问题类:测试是戏台):红的原因是否=该缺陷、断言测的是根因还是症状、有无安慰剂/前提共谋;核对第 3 步落档的红证据——没有红过的记录,测试可信度按不成立处理
• 所有缺陷零豁免；独立通道不可用时才记 self-degraded；≤2 轮上限同样生效
• 审查凭证落盘：输出全文 tee 到 {SPECS_DIR}/.reviews/fix-{slug}-r{轮次}.md（纪律同 N4）——进第 6 步前必须真跑 ls {SPECS_DIR}/.reviews/fix-{slug}-r*.md,命令无输出=审查未发生,退回补审;凭证文件名写进第 7 步收口输出（文字卡点拦不住是实测结论,机械命令才算数）

6. 回归（按波及面，不是只看 bug 消失）

• 跑第 3 步防护网测试（红→绿）+ 存量测试全量（对照基线）
• 按第 2 步波及面清单逐项走一遍关键流（同 B2 口径：波及面=回归范围）
• 回归失败的回路（显式分支,不许临场发挥）：任何一项红 → 退回第 4 步重修,重修后必须复审且轮次并入第 5 步的 ≤2 轮总上限——上限耗尽仍打转 = 根因判断可疑,按升级出口处置,不许无限修-回归循环

7. 落盘（审计链闭合）

• 缺陷档案：{SPECS_DIR}/fixes/{YYYYMMDD}-{简短slug}.md——现象 / 复现步骤 / 根因 / 修法（含放弃的方案）/ 波及面与回归结果 / 测试文件路径。这是缺陷知识库，同类 bug 再犯先查这里
• METRICS.md 追加一行：Feature 列写 fix，任务列写档案文件名，其余列同口径（轮次/拦截数/人工介入）
• 根因具普遍性（如"平台 API 返回结构变了"）→ 追记 LESSONS.md（[已结构化]/[仅记忆] 分级同 N5）
• git commit：fix: {一句话} (档案: fixes/xxx.md)，审查摘要进 commit message（同 N4）
• 运行日志事件：task_start/review/task_done/done 照记，node 字段写 FIX

微缺陷快速通道（四个硬门槛全中才准走）

门槛是客观项不是判断题——"感觉这个 bug 很小"不构成理由，四条全中才走，任一不中走完整七步：

• 只改文案/样式/配置常量——不新增、不修改任何条件分支与函数签名
• 单文件且 diff ≤ 10 行
• 波及面为零（改动处无被其他模块引用的行为；有业务地图查 08 映射表核实）
• 有截图/文案前后对照可作验收证据

快速通道可省：第 3 步防护网测试、第 6 步全量回归（用前后对照截图代替）。 不可省：独立审查（凭证照落）、缺陷档案（显式标注 快速通道）、METRICS 行（Feature 列写 fix-lite）。 快速通道的审查特化：独立审查是该通道的主要质量防线，第一职责是复核四个客观门槛；diff 任一项不符或波及面存疑即打回完整七步。

fix-lite 的占比进运行日志——快速通道被滥用（占比异常高/出现分支改动混入）时收紧门槛，数据说了算。

输出格式（每个缺陷收口时）

🔧 缺陷闭环: {slug}
根因: {一句话}
修法: {一句话} | 放弃方案: {有则一句话,无则省}
防护网: 新增 {测试文件}(红→绿) · 存量基线 {N} 项无退化
审查: 独立审查({channel}) {通过/N轮N条} | 回归: 波及面 {N} 项通过
档案: fixes/{文件名}   METRICS 已记

边界

• 不承接：新功能（走 $cm-prd）、需求变更（走 $cm-prd --change）、架构级返工（升级出口交人立项）
• specs 目录没有 fixes/ 子目录时自动创建；没有 specs 目录的裸项目也可用：档案落代码项目 docs/fixes/，审查凭证落 docs/fixes/.reviews/（第 5 步卡点同样生效），METRICS 跳过