codex-app-server/cloud/skills/software-engineering/TRANSPLANT-PREP-244.md

# #244 向 v0.3 / v0.4 / v0.5 的移植准备（不是移植本身）

> 状态：准备文档。移植本身只能在合并时做，本轨不改
> v0.3 / v0.4 / v0.5 文本，不声称已移植、已部署。
> 本轨的包内改动（见 CHANGELOG）只涉及 v0.2 + #244 线：
> 附录源文件 00-09、校验脚本 00-09 版、本准备文档、
> 移植检查脚本与测试；SKILL.md 仅改 1 行附录标题格式。

## 0. 基底与来源（复核于 2026-10-31）

- 主线基底：`origin/main` = `aebc623`（Merge PR #201）。
- 来源 #244：`feat-audit-pushback` @ `39966bd`，PR #244
  OPEN / MERGEABLE，SKILL.md 1272 行、81,565 字节，
  相对 v0.2（49,326 字节、813 行）纯加法 +459 行，
  分 4 段（行号均为 #244 文本内行号）：
  - A. 角色矩阵行：L134，1 行。
  - B. 主节“独立审计与自动推回”：L327–L730（+ L731 空行），
    405 行。内含：审计与推回 L327–L441、推倒重做 L442–L554、
    三条收紧 L555–L641、QA 全链路 L642–L730。
  - C. 校验新增项：L757–L766，10 行（审计项 L757–L761、
    QA 项 L762–L766）。
  - D. 附录 09 章：L1230–L1272，43 行（空行 + `---` +
    标题 L1233 + 正文 38 行 L1235–L1272）。
- 目标 v0.3：PR #199，`feat-software-engineering-v03` @
  `19783b0`，SKILL.md 905 行、56,607 字节。
- 目标 v0.4：PR #205，`feat-full-auto` @ `d6522ba`，
  SKILL.md 993 行、63,893 字节（堆叠于 v0.3）。
- 目标 v0.5：PR #207，`feat-swe-g7g8` @ `8a68100`，
  SKILL.md 1326 行、88,540 字节（堆叠于 v0.4）。
- 附录溯源 #217：`feat-skill-appendix-provenance` @
  `e6b5014`，PR #217 OPEN / MERGEABLE；其 00-08 源文件
  与从 #244 附录拆出的 00-08 源文件逐字节一致
  （#244 未改 00-08 章正文）。
- 生产现况：仍跑技能 v0.2（49,326 字节）；工作区草稿
  `~/workspace/software-engineering-skill/` 是更旧的 v0.2
  草稿（40,759 字节、686 行），绝不能从它推、不能用它
  覆盖任何部署版（差异清单见 §5）。

## 1. 移植 diff：锚点（每目标一行号均为该目标文本内行号）

| 段 | 插入位置（统一规则） | v0.3 | v0.4 | v0.5 |
|---|---|---|---|---|
| A 矩阵行 | QA 行之后、验收行之前 | QA 行 L138 | QA 行 L206 | QA 行 L359（该行已是跨视口措辞，行本身不动） |
| B 主节 | “失败、续跑与成本”节末、“诚实边界”节首之前 | 失败节 L363–L374，诚实边界 L376 | 失败节 L433–L444，诚实边界 L446 | 失败节 L597–L608，诚实边界 L610（标题带“v0.5 后置占位版”后缀，锚点按前缀匹配） |
| C 校验项 | “有一项为否”行之前（即全部已有校验项之后，不拆散 v0.3 / v0.5 新增项） | 有一项为否 L406 | 有一项为否 L478 | 有一项为否 L657（只插审计项，QA 项停下，见 §2） |
| D 附录章 | 文件末尾、上一章正文之后：空行 + `---` + 空行 + 标题 + 空行 + 正文 | 08 章 L873 起、文件末 L905 | 08 章 L961 起、文件末 L993 | 10 章 L1277 起、文件末 L1326，编号改为 11（见 §3） |

规则语义不变性：除 B 节内的改写（§2 的 R1/R2）、
删句（§2 的部分停下）、C/D 的编号与 §4 的引用删除外，
移植是纯插入；目标文本已有行不得改写、不得删除
（移植后检查的“无覆盖”子序列校验钉住这一点）。

## 2. 逐段分级：合并 / 合并+移植注 / 部分停下 / 整段停下

分级定义：合并 = 原文照搬；合并+移植注 = 原文照搬，
但移植轨须在执行记录里写清注明的口径映射（不改规则）；
部分停下 = 该段内标明的句子不移植，其余句子移植；
整段停下 = 整段不移植，须用户或移植轨先定重写方案，
绝不能悄悄改语义后硬搬。

### 2.1 A 矩阵行：三目标全部合并

行文本与 #244 L134 相同。v0.5 的 QA 行已是跨视口措辞，
审计行插在 QA 行与验收行之间，不动运维 / 迭代两行。

### 2.2 B1 审计与推回（L327–L441）

- 五职分开（写 / 测 / 审 / 执行 / 签字）：
  v0.3 合并；v0.4 / v0.5 合并+移植注——#244 写
  “执行合并 / 发布是人或宿主操作”，在全自动模式下
  执行人字段填主机自动执行器 `full-auto-executor` +
  installation id（v0.4 全自动节原话），签字人与执行人
  字段仍须不同，分离规则本身不变。
- 硬门禁接口约定（`merge_blocked` / `release_blocked`）
  与账本接口（`build_ledger_entry` /
  `validate_ledger_chain`）的“目前是提案”说明：
  三目标全部合并（提案状态未变；注意 #244 的
  “第 1 轨 / 第 4 轨”指审计加固轨内部轨号，
  不是本批 9 分项的第 1–4 项，不得混淆）。
- “与已有回路的关系”段（G5 复用 + G7 并行 + 全自动并行
  + 注意句）：
  - v0.3 部分停下：G5 复用句移植；G7 并行句、全自动并行句、
    注意句不移植（v0.3 文本里 G7、全自动两个回路都不存在，
    照搬会成悬空引用）。
  - v0.4 部分停下：G5 复用句与全自动并行句移植；G7 并行句、
    注意句不移植（v0.4 无 G7；注意句称“全自动尚未出现”
    在 v0.4 已为假）。
  - v0.5 合并：G7 热修复回路（发布后应急）与全自动 CI
    回路在 v0.5 文本里真实存在，且口径与 #244 的描述一致
    （推回是合入前、热修复是发布后应急；计数独立）。
- 推回上限段“与全自动 CI 自动修复限 3 次同口径”括号：
  - v0.3 部分停下：括号改写为“推回上限独立于其它修复回路
    的轮次预算，一方不得消耗另一方的预算”（上限 3 轮
    本身保留；CI 轮次在审计前、推回轮次在审计后的
    排序句随括号一并删去，v0.3 无此回路可排序）。
  - v0.4 / v0.5 合并：v0.4 全自动节原话即“CI 自动修复
    循环限 3 次”，口径一致；排序句（CI 轮次在审计前）
    是 #244 的定义，v0.4 文本未另定顺序，不冲突。
- R1 改写（三目标）：审计节引言的移植警告段
  （“本节是按主线 v0.2 文本写的……绝不能用本文件
  覆盖它们”）不得照搬，移植时改写为：
  “移植注：本节源自审计加固轨，移植时已按本文件对应章节
  的回路口径对齐。”（前文“G5 缺陷回路、合并拆分、
  G6 用户验收的原意都不变”保留。）

### 2.3 B2 推倒重做（L442–L554）

- 计数口径、阈值 `> 3`、只推倒该模块、先判根因、
  重做上限 1 次、成本与配额：三目标全部合并。
- 状态与账本段尾句“与 G7 热修复回路并行……与全自动
  CI 自动修复并行且计数独立”：
  - v0.3 部分停下：尾句整体改为句号结尾（只保留
    “与 G5 缺陷回路复用修复执行通道”）。
  - v0.4 部分停下：删 G7 分句，保留全自动分句。
  - v0.5 合并。

### 2.4 B3 三条收紧（L555–L641）

- 收紧一（第三次失败先判根因、结构性提前推倒、
  接近完成 targeted 续轮）、收紧二（只推倒实现代码、
  旧测试全过为第一道门）、收紧三前两条（审计兜底三件套、
  判错纠错路径）：三目标全部合并。
- 收紧三末段“验收失败导致的推倒要先通知用户”
  （L635–L640，推倒前须通知并确认新方向、未确认前
  不得静默重开）：
  - v0.3 合并（无全自动模式，无冲突）。
  - v0.4 / v0.5 整段停下：v0.4 全自动节称“只有四类情况
    回头问用户”（成本超阈值、删数据 / 改权限 / 对外账号、
    外部服务要人工验证、自动修复连续失败），验收失败触发
    推倒前确认新方向不在四类明文之内；成本超阈值通道与
    自动修复连续失败通道能否覆盖它，须用户拍板二选一：
    （a）全自动四类表增加第五类“验收失败触发推倒前确认
    新方向”；（b）该确认限定默认模式，全自动模式下走
    已有升级通道。移植轨不得擅自选（a）或（b），
    本轨的草稿移植已把该段排除（见 §6）。

### 2.5 B4 QA 全链路（L642–L730）

- v0.3 合并+移植注：
  - 自测三项（单元 + 契约集成 + 手工冒烟）是下限，
    不是替换：v0.3 客户端附录章的交付前自测共 4 项，
    第 4 项“跨端一致性自查”继续有效，不得因“三项”
    之名删掉。
  - agent 专属六项集合与 v0.3 完全相同（单端复核 3 项：
    沙箱越界、危险动作审批、token / 配额超限；
    跨端 E2E 3 项：长任务超时和取消、断网续跑、
    模型 503 重试）；v0.3 的归属拆分继续为准，
    #244 未另定归属，不冲突。
  - QA 分工（单端复核 + 跨端 E2E 两条线）与 v0.3
    P1-3 的 QA 拆分是同一拆分，#244 是 elaboration，
    不是替换。
- v0.4 合并+移植注：同 v0.3（v0.4 继承 v0.3 的
  QA 拆分与归属；全自动模式不改变 QA 分工）。
- v0.5 整段停下：v0.5 已定口径把 QA 第二部分改为
  跨视口 E2E（矩阵的行是手机 / 平板 / 桌面视口，
  G5 门改为跨视口一致性），而 #244 QA 节至少 4 处
  与之正面冲突：① 分工句“跨端 E2E 跑遍各端”；
  ② G5 过关句“跨端一致性”；③ 矩阵句“覆盖全部已选
  客户端”；④ 诚实例外句“iOS / Android 编不出来时
  结论只能写代码评审 + Web 核心验证”（v0.5 对
  iOS / Android 是后置占位、不进 QA 通过表；
  Mac 句仍成立，但整节不能只拆一句硬搬）。
  因此 v0.5 的 QA 节须由移植轨重写为视口版后再移植，
  不得把跨端版原文搬进 v0.5。附带：QA 节内 agent
  六项集合本身与 v0.5 一致（归属改为跨视口 E2E），
  视口版重写时六项清单原样保留。
- R2 改写（三目标，v0.5 的 QA 节停下故不适用）：
  QA 节引言“QA 要求以生产 v0.2 技能为准……移植警告
  ……技能正文 diff 全是加法”不得照搬——移植后 diff
  本来就不是纯加法（含 R1/R2 改写、删句、§4 删引用、
  v0.5 章节号重编），“全是加法”句在移植文本里为假。
  改写为：“本节是独立审计与 QA 部分的补充验收标准，
  与自动推回、推倒重做、三条收紧并列，不覆盖已有规则；
  已有规则语义不改，只补测试机制。”

### 2.6 C 校验项（L757–L766）

- 审计项（三目标全部合并）：签字人独立、安全签字无条件、
  自动推回阻塞、推倒分支处理，均为目标无关表述。
  插入位置统一在“有一项为否”行之前（已有 v0.3 / v0.5
  新增项之后），不拆散已有校验项。
- QA 项：v0.3 / v0.4 合并（“每端自测三项”按 2.5 的
  下限口径读；“跨端矩阵覆盖全部已选端”在 v0.3 / v0.4
  仍成立）；v0.5 整段停下（“跨端矩阵覆盖全部已选端”
  与视口矩阵冲突；“未编译端只写代码评审 + Web 核心验证”
  与 iOS / Android 后置占位冲突；随 QA 节视口版重写
  一并改写，不得照搬）。

### 2.7 目标版本已有内容在移植后必须仍在（检查脚本钉住）

- v0.3：目录隔离自动检查（命令 + 输出记入合并记录）、
  派生校验表 8 项、子任务精简包、QA 拆分、任务间问答
  默认策略（`docs/decisions.md` 只追加）。
- v0.4：全自动模式（API 优先、一次授权、full-auto-executor、
  FULL_AUTO_ENABLED、CI 自动修复限 3 次）+ 全部 v0.3 项。
- v0.5：G7 发布后运维与观察期、G8 迭代与规模化、
  附录 09-ops / 10-iteration、跨视口口径 + 全部 v0.4 项。
- 绝不能用 #244 的 v0.2 文本覆盖上述任一目标文本：
  覆盖会丢 v0.3 的目录隔离检查、v0.4 的全自动、
  v0.5 的 G7/G8（#244 正文自己的移植警告亦如此要求）。

## 3. 附录章节号对应表（不要把章节号搞混）

| 线 | 附录章节 | 源文件 | 标题格式 |
|---|---|---|---|
| v0.2（#217） | 00–08 | `templates/roles/00-…08-*.md` | `## 附录角色：<id>（来源 templates/roles/<id>.md）`（严格式） |
| v0.2 + #244（本轨包） | 00–08 同上 + 09-auditor | 增加 `templates/roles/09-auditor.md` | 09 标题已规范化为严格式；#244 原标题“（独立审计，新增）”不符合 #217 校验正则，移植时一律用严格式，称谓保留在章首 `# 角色模板：独立审计……` 行 |
| v0.3 / v0.4 移植后 | 00–08 同上 + 09-auditor | 增加 `templates/roles/09-auditor.md`（与本轨包同一文件） | 严格式 |
| v0.5 移植后 | 00–08 同上 + 09-ops + 10-iteration + 11-auditor | 增加 `templates/roles/11-auditor.md`（正文与 09-auditor 相同，只改编号与标题；另须在移植时从 v0.5 附录机械拆出 09-ops / 10-iteration 源文件，方法同 #217，否则校验脚本无法覆盖 v0.5 全表） | v0.5 现有 09/10 标题带“，v0.5 新增”后缀，不符合 #217 严格正则；移植时校验脚本的标题正则须放宽为允许可选后缀，或把 09/10 标题规范化为严格式——二选一由移植轨定，本轨不擅自改 v0.5 标题 |

校验脚本期望表（`tools/check_appendix.py` 的 EXPECTED_IDS）：
本轨包为 00–09；v0.3 / v0.4 移植后仍为 00–09；
v0.5 移植后必须重定基为
`00-…-08, 09-ops, 10-iteration, 11-auditor`，
绝不能拿本轨的 00–09 表直接验 v0.5 文本。
附录生成器（`--emit`）按期望表拼接：09-auditor 源文件缺失时
重跑会掉 09 章；本轨补齐后 `--emit` 输出 10 章标题 + 正文。

## 4. templates/artifacts 缺失模板名：二选一决策——删引用

SKILL.md 正文在 6 处引用 `templates/artifacts/`，
而 #217 后的包里 `templates/` 只有 `roles/`，没有
`artifacts/`；`skill_seed` 只拷 SKILL.md，模板文件
即使补进包也不会进租户目录。本轨决策：删引用
（不补模板文件进包、不改播种规则）。取舍如下：

- 为什么不选补齐：补齐为“编辑源”不能修复租户侧
  悬空引用（租户仍看不到文件）；要真正修好须另做
  二选一之外的事——把 5 份模板嵌进附录（SKILL.md
  膨胀约 8KB，且 v0.3 / v0.4 / v0.5 各需一份）或改
  播种规则（生产行为变更，另起一轨）。两种都超出
  本轨范围，且补齐后声称“已修好”会是假话。
- 删引用为何损失可控：6 处引用之后都紧跟内联实质，
  删路径句不丢规则（见下表）；失去的只是现成的
  填空式表单（工作区草稿 `templates/artifacts/` 下 5 份
  文件仍在，仅作历史参考，不进包、不播种）。

| # | 位置（6 处在三目标文本里措辞相同） | 删 / 改写 | 替代（内联实质已在正文里） |
|---|---|---|---|
| 1 | 门禁表 G1 行 | “PRD 按 `templates/artifacts/prd-outline.md` 写完”→“PRD 按产品经理附录章节所列大纲写完” | 产品经理附录章所列 PRD 大纲 1–6 项（含 agent 三节） |
| 2 | 接单选型节 | 删“问卷模板在 `templates/artifacts/intake-questions.md`。”一句，保留“最关键的六问：” | 六问全文紧随其后 |
| 3 | 测试与验收节 | 删整行“验收清单模板在 `templates/artifacts/acceptance-checklist.md`。” | 其后验收语义（用户逐项确认、按端分别做）完整保留 |
| 4 | 产品经理附录章产出 | “按 `templates/artifacts/prd-outline.md` 写一份 PRD”→“按下面大纲写一份 PRD” | 其后大纲 1–6 项全文 |
| 5 | 架构师附录章产出第 4 项 | “协议模板见 `templates/artifacts/` 下的 agent 任务契约模板。”→“（Agent 协议、状态机、错误 taxonomy 的要素见本章第 4、5、6 项。）” | 本章第 4/5/6 项 + G0 执行模型、权限边界、审批模型 |
| 6 | 验收附录章协调员准备第 1 项 | “按 `templates/artifacts/acceptance-checklist.md` 生成”→“按 PRD 验收标准生成” | 其后“每一项对应 PRD 里的一条验收标准” |

工作区草稿的 5 份 artifacts 文件（acceptance-checklist、
agent-task-contract、coordinator-spawn-example、
intake-questions、prd-outline）与本决策的关系：
`coordinator-spawn-example.md` 从未被 SKILL.md 引用，
其余 4 份对应上表 4 个文件名；决策后它们都不进包，
草稿侧标注为历史参考（见 §5 同步清单）。

## 5. 工作区草稿与部署版的同步清单（本轨只给清单，不执行）

差异清单（实测，2026-10-31）：

- 草稿 SKILL.md（40,759 字节、686 行）vs 生产部署版
  v0.2（49,326 字节、813 行）：草稿是严格更旧的子集，
  生产版比草稿多 7 处增补（含 G0 仓库冻结项与 G0.5
  建仓门），另有 1 处 G0 行措辞随增补而扩展；无反向
  增补。结论：同步方向只能是部署版 → 草稿，
  绝不能用草稿覆盖部署版或任何 PR 文本。
- 草稿 `templates/roles/` vs #217 源文件：01/02/03/05/06/08
  六份逐字节一致；00/04/07 三份草稿更旧更短
  （草稿 00: 4094 字节 vs 源 6157 字节；04: 3242 vs 4087；
  07: 1559 vs 2121），同步时以源文件为准。
- 草稿 CHANGELOG / README vs #217 CHANGELOG / #225 README：
  是两套不同的文档（草稿版自述“仅起草、未提 PR”），
  同步时以包内版本为准，草稿版不合并、不覆盖。
- 草稿独有：`templates/artifacts/` 5 份、
  `WALKTHROUGH-agent-tool.md`、verification/ 下各轨摘要。
  前者按 §4 决策不进包；后两者是工作区侧资料，不进包。
- 各 PR 文本字节数：v0.3 56,607 / v0.4 63,893 /
  v0.5 88,540 / #244 81,565（单位：字节；行数见 §0）。

合并部署后同步回草稿的步骤清单（按顺序，部署完成前不动草稿）：

1. 先合 #199 → #205 → #207 链（v0.3 → v0.4 → v0.5，
   本就是堆叠顺序），再合 #217 → #225（附录溯源 →
   README），再合 #244 → 本轨（审计加固 → 移植准备），
   最后由移植轨按 §1–§4 把审计段落移植进已合并的
   v0.5 文本并解决 §2 的停下项（用户拍板后）。
   顺序要点：移植准备轨（本轨）不得早于 #244 合并；
   若 #217 先合并，本轨的校验脚本与 CHANGELOG
   会冲突，解法写死为保留 00-09 版（见 §6）。
2. 部署后，以部署版包（`cloud/skills/software-engineering/`）
   为准覆盖草稿：SKILL.md、`templates/roles/`、
   `tools/`、CHANGELOG.md、README.md。
3. 草稿侧保留不动：verification/ 全部摘要、
   `WALKTHROUGH-agent-tool.md`；`templates/artifacts/`
   标注为“已删引用、仅历史参考”，不删除（删了会丢
   表单原件的唯一副本），也不进包。
4. 校验脚本（部署后在草稿目录外跑，不污染草稿）：
   `sha256sum` 对比草稿 SKILL.md 与部署版 SKILL.md
   必须一致；字节数与行数与部署记录一致；
   `python3 tools/check_appendix.py` 在部署版包上通过
   （章节数按最终合并的章节表：v0.5 线为 12 章
   00–08 + 09-ops + 10-iteration + 11-auditor）；
   `grep -c templates/artifacts SKILL.md` 在最终部署版
   为 0（决策 B 落地后）。
5. 同步后草稿 SKILL.md 文首版本行由部署轨负责更新
   （草稿与 v0.2 部署版文首目前都自述“仍是草稿、
   未提 PR”，该自述在部署版里已 stale，不由本轨改）。

## 6. 本轨堆叠与合并顺序（PR 正文亦写清）

- 本轨分支 `feat-skill-transplant-prep` 堆叠于
  `feat-audit-pushback`（#244，`39966bd`）之上，
  PR base 设为 `feat-audit-pushback`（不是 main），
  以便 09 章节与源文件在真实包上可验。
- 本轨包内改动：SKILL.md 仅 1 行标题格式规范化；
  其余为新增文件（源文件 10 份、校验脚本 2 份、
  CHANGELOG、本准备文档、测试 2 份）。零规则改动。
- 合并顺序：#217 → #225 → #244 → 本轨 →
  （移植轨，另起一轨，须用户先拍板 §2 的停下项与
  §4 决策）→ v0.3 / v0.4 / v0.5 链的最终合并。
  注意 #199 / #205 / #207 链与 #244 / #217 链的
  SKILL.md 合并本身即移植动作，不在本轨完成。
- 已知的合并冲突点（若 #217 先合并）：
  `tools/check_appendix.py`（00-08 vs 00-09，保留 00-09）、
  `CHANGELOG.md`（两段条目并存）、
  `cloud/tests/test_skill_appendix_provenance.py`
  （00-08 版 vs 00-09 版，保留 00-09）；
  `templates/roles/00-…08-*.md` 为 identical-add，不冲突。
- 正式移植 diff 与本轨准备 diff 的区别：本轨的
  `check_transplant.py --apply` 输出是草稿（/tmp 内，
  不进提交），供评审核对锚点与停下项；正式移植 diff
  是移植轨在合并时对目标文本的真实改动，须另经
  CI 与移植后检查（本脚本 `check-transplanted` 模式）
  全部通过，且 §2 的停下项须先有用户拍板或重写版。

## 7. 检查脚本用法

```sh
# 锚点与保留标记（对真实三目标文本已跑过，见验证摘要）
python3 cloud/skills/software-engineering/tools/check_transplant.py anchors \
  --source244 <244 文本> --target <v03|v04|v05 文本> --target-id v03|v04|v05
# 草稿移植（只写 /tmp，不进提交；停下段落列在 stderr）
python3 cloud/skills/software-engineering/tools/check_transplant.py apply \
  --source244 <244 文本> --target <目标文本> --target-id v03|v04|v05 \
  --out /tmp/draft-<目标>.md
# 移植后检查（正式移植轨的门禁之一）
python3 cloud/skills/software-engineering/tools/check_transplant.py check-transplanted \
  --source244 <244 文本> --target <目标文本> --target-id v03|v04|v05 \
  --transplanted <移植后文本>
# 附录校验（本轨包内）
python3 cloud/skills/software-engineering/tools/check_appendix.py
```

## 8. 未做项与诚实边界

- 未移植：v0.3 / v0.4 / v0.5 文本在本轨零改动；
  草稿移植输出只在 /tmp，不进提交、不进 PR。
- 未验证：真实 PG、真实任务冒烟（按任务要求不做）；
  本轨证据全部是本地文本比对与单测，不冒充生产验证。
- 未做：CI 清理、台账钩子、shell 白名单、发布接线、
  分支保护、v1.1 契约确认——均属其它轨或用户侧。
- 用户侧仍需拍板（见验证摘要末节）：§4 删引用决策、
  §2.4 收紧三确认段的（a）/（b）、§2.5 v0.5 QA 节
  视口版重写方案、§3 v0.5 标题正则放宽 vs 规范化、
  §5 同步顺序。