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. 检查脚本用法

# 锚点与保留标记（对真实三目标文本已跑过，见验证摘要）
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 同步顺序。