[codex] 补齐 sync pass 执行契约

[wlvh]

背景 & 目标（Why）

本 PR 收紧 scripts/OPERATIONS.md 中 4 个 Sync Agent Pass 的执行指引。问题来自执行 agent 视角复核：外部顺序合理，但每个 pass prompt 单独复制给新对话时，必须明确先读取 .coding_workflow/diffs/ 产物，并分清脚本生成的 PR body 结构真相源和手写执行语义。

目标是让 pr_body_skeleton.md 承担 sentinel、表头、Repo Facts headings 等结构真相源，让每个 PASS prompt 直接携带 skeleton 看不出来的执行规则；删除共享 §2.0，避免用户每次新开对话时还要额外记忆或复制公共段落。

---

实现方案（How）

• 在 Quick Start 输出后补充执行入口，同时补充非 sync sentinel PR_BODY.md 的恢复路径。
• 收敛 Quick Start 人机分工：用户只复制对应 PASS code block 到新对话；.coding_workflow/diffs/agent_workorder.md 是给执行 agent 的本轮工单和机器信号，用户不阅读也不影响启动下一步。
• 保留每个 PASS prompt 的整体目标说明，但改成稳定的 workflow docs sync 总目标，避免旧的“以 AGENTS.md 为首”表述和 pass owned docs 边界冲突。
• 删除 §2.0 共用执行契约：## 2 只保留一行复制说明，执行时只复制对应 PASS code block。
• 将最小共用执行规则复制进 4 个 PASS prompt：每个新对话只复制对应 PASS code block，也能知道读取工单/skeleton、不得手改 auto 区/sentinel、agent-owned section 写入边界和 Full Document Reconcile 填写规则。
• 将 PASS prompt 开头从“本文档”改成“当前任务”；PR_BODY.md 初始化动作只保留在“必须读取”清单，避免共用规则和步骤清单重复。
• 收敛 完成后 块：聊天回报只保留普通 sync 闭环和是否留下 待判断；adopted / rejected / downstream 详情以 Full Document Reconcile 为准。
• 进一步收口事实源：Full Document Reconcile 在每个 PASS prompt 内解释为 PR_BODY.md 的文档语义对账表；PR 提交 agent 以 PR_BODY.md 和 final gate 为准，不再依赖 PASS 4 聊天摘要。
• 删除 agent 自填状态面：ready_for_next_pass、Sync Pass Status / pass_handoffs、PASS_STATUS_COLUMNS、pass status 渲染函数和 final gate 状态检查全部移除。
• Full Document Reconcile skeleton 的所有语义列默认 待补充，不再预填 none / 待判断，要求 agent 显式判断后再改成具体内容、none 或 待判断。
• skeleton 回归测试显式锁住 Full Document Reconcile 每行 5 个语义列全为 待补充，并禁止旧的 none / 默认 待判断 组合回归。
• final gate 只守低成本机械门：sentinel / auto 区一致性、blocking sync 状态、agent-owned 待补充 残留和 template residue；待判断 允许保留给 reviewer 和用户判断。
• reviewer prompt 改为按 Full Document Reconcile 审 pass evidence / propagation，不再要求 pass status ready。
• README.md 的 Workflow Docs Sync 维护说明同步改为 Full Document Reconcile / Remaining Human Decisions 交接模型，避免工具维护文档继续指向旧状态表。
• 删除无人消费的 scratch markdown：不再生成 .coding_workflow/diffs/installation_status.md 和 .coding_workflow/diffs/full_reconcile_report.md，对应信息保留在 sync_state.json 和 PR body auto 区。
• 精简普通 sync stdout：只保留 sync 成功、upstream / project 短 SHA、commit-pinned runbook URL、下一步复制 PASS prompt、agent workorder 路径，不再打印旧读序和旧 first action。
• 将 4 个 PASS prompt 改成 6-block 自包含格式：前置条件 / 必须读取 / 只允许修改 / 必须填写 / 停止条件 / 完成后。
• 保持 workorder 与 OPERATIONS 分工：workorder 只保留本轮文件处理清单和 commit-pinned 操作手册 URL，OPERATIONS 提供每个 pass 的语义判断和写入规则。
• 拆分 drift test：pr_body_skeleton 测试负责结构常量；每个 PASS prompt 自包含测试负责确认 §2.0 已删除且 guardrails / owned docs 不漂移；新增 final gate 测试覆盖 待补充 拦截和 待判断 放行。
• 遵循 README.md 的 sync 工具维护边界：本 PR 不改写下游项目会继承的 AGENTS.md / TESTING.md 模板。
• 将文档漂移收敛为 3 个可审计类别：class-1 template/missing、class-2 upstream、class-3 code/test/behavior drift，并要求每个 PASS 在 Full Document Reconcile 的 evidence 列显式覆盖三类；未发现也必须写 none。
• 在 PASS 3 增加测试漂移机械信号菜单：find 统计测试文件行数、grep 扫测试函数 / 类、git log --since='3 months ago' -- tests/ 看近期热改；命令只是示例，agent 必须按项目等价工具改写并把实际命令写入 evidence。
• 在 PASS 4 要求 downstream impact 逐 pass 追溯 class-3 漂移的数量、闭合位置和 deferred 去向，避免“反向闭合”停留在口头声明。

---

变更范围（What）

来自 git diff --name-only origin/main...HEAD：

文件 / 目录	变更类型	说明
README.md	修改	更新 Workflow Docs Sync 维护说明：语义交接从旧 pass status 模型改为 Full Document Reconcile / Remaining Human Decisions。
scripts/OPERATIONS.md	修改	删除 §2.0 公共执行契约，把 4 个 pass prompt 保持为执行 agent 可单独复制的 6-block 格式，并把最小共用执行规则复制进每个 PASS prompt；去掉“本文档”指代、用户手动打开工单要求、重复初始化规则、重复聊天回报和 PASS 4 聊天摘要事实源；补充三类漂移定义、PASS 3 机械信号菜单和 PASS 4 class-3 反向闭合要求。
scripts/sync_coding_workflow.py	修改	删除 pass_handoffs / Sync Pass Status / ready_for_next_pass 相关渲染和 final gate 检查；保留 Full Document Reconcile，将其语义列默认值统一为 待补充，把 final gate 占位符扫描收窄到 agent-owned sections，并删除两个重复 scratch markdown 生成、精简 stdout / workorder。
scripts/sync_pr_review_system.md	修改	reviewer 语义审查改为检查 Full Document Reconcile 的 per-pass evidence、downstream impact 和 propagation。
tests/test_sync_coding_workflow.py	修改	新增 test_pr_body_skeleton_renders_sync_constants、test_each_pass_prompt_contains_common_execution_rules 和 final gate 占位符测试；删除旧 pass status 测试，改由 skeleton / PASS prompt / final gate 分别守住结构、执行规则和机械门，并锁住 Full Document Reconcile 默认行不预填语义判断；锁住三类漂移定义、PASS 3 示例命令和 PASS 4 class-3 追溯 literal。

---

文档同步

受影响文档：

• README.md
• scripts/OPERATIONS.md
• scripts/sync_pr_review_system.md

未修改：

• AGENTS.md
• TESTING.md
• PR_Checklist.md
• architecture.md
• capability_contract.json
• interact.md
• docs/business_user_guide.md

说明：

• 本 PR 改的是 sync 工具自身的 PR body / final gate / reviewer 交接合同，已同步 README.md、scripts/OPERATIONS.md 和 scripts/sync_pr_review_system.md。
• architecture.md、capability_contract.json、interact.md 和 docs/business_user_guide.md 是目标项目继承的模板 / 样本文档；本 PR 不改变下游项目能力边界或用户可见行为，因此不改这些模板。
• README.md 的“代码项目核心文档 / Workflow Docs Sync”已明确：开发 sync 工具时，工具自身说明、实现文件清单和回归测试说明落在 README.md 和 scripts/ 下；这些要求不写入下游项目会继承的 AGENTS.md / TESTING.md / PR_Checklist.md 模板。

---

测试证据

git diff --check
# OK
python3 -m py_compile scripts/sync_coding_workflow.py tests/test_sync_coding_workflow.py
# OK
python3 -m unittest tests.test_sync_coding_workflow.SyncWorkflowTests.test_pr_body_skeleton_renders_sync_constants tests.test_sync_coding_workflow.SyncWorkflowTests.test_generated_workorder_stays_thin_and_points_to_runbook
# Ran 2 tests in 0.430s
# OK
python3 -m unittest discover -s tests
# Ran 15 tests in 6.735s
# OK

---

Review / 修复记录

轮次	来源	问题摘要	判断	处理结果	证据
R0	Claude review + Codex 复核	4 个 sync pass 的初始化顺序、owned docs、锚点优先级、TESTING 术语和 PASS 4 模板覆盖决策说明不够稳定。	真实存在	收紧 scripts/OPERATIONS.md：统一固定读取顺序，明确 PASS 1 拥有 Repo Facts Map、PASS 2 contract/interact 锚点、PASS 3 只改 TESTING.md 策略、PASS 4 反向闭合边界。	scripts/OPERATIONS.md
R1	用户反馈 + Claude/GPT 合意	从执行 agent 视角看，pass prompt 仍依赖上文，缺少 sentinel、pass_id、表头和完成命令的自包含执行契约。	真实存在	新增 §2.0 公共执行契约，将 4 个 pass 改成 6-block 自包含 prompt，并新增 drift test 防止契约字面值与脚本常量漂移。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R2	用户复核 + README.md	sync 工具维护规则已说明工具自身说明和回归测试说明不写入下游模板，AGENTS.md / TESTING.md 不应进入本 PR。	真实存在	撤回 AGENTS.md / TESTING.md 改动，只保留 scripts/OPERATIONS.md 和 drift test。	README.md, git diff --name-only origin/main...HEAD
R3	用户要求修复 + Codex 复核数据回路	§2.0 重复了 pr_body_skeleton.md 已自动生成的 sentinel、表头和 Repo Facts headings；drift test 也把结构真相源和手写语义合同混在一起。	真实存在	收敛 §2.0 为 skeleton 看不出来的执行规则；新增 skeleton 渲染测试，原 drift test 改为只守 OPERATIONS.md 手写语义和 owned docs。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R4	用户反馈	每个 pass 都要求新开对话，不能要求用户记得额外复制 §2.0；必须降低用户心智成本。	真实存在	将最小共用执行规则复制进 4 个 PASS prompt，并新增测试确保每个 copyable PASS prompt 自带 guardrails。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R5	用户反馈	规则已经复制进 4 个 PASS prompt 后，继续保留 §2.0 会形成第二阅读入口，增加用户心智负担。	真实存在	删除 §2.0 共用执行契约，## 2 只保留复制说明；测试断言该 heading 不再出现，并继续检查每个 PASS prompt 自带 guardrails 和 owned docs。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R6	用户反馈	PASS prompt 仍有“本文档”模糊指代，且 PR_BODY.md 初始化规则同时出现在“共用执行规则”和“必须读取”里。	真实存在	PASS prompt 开头统一改成“当前任务：只执行 ... 不要执行其他 PASS”；共用规则只保留结构真相源和写入边界，初始化动作只保留在“必须读取”清单；测试断言每个 PASS 不含“本文档”且初始化规则只出现一次。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R7	用户反馈	Full Document Reconcile 已承载 adopted / rejected / downstream 详情，完成后 块再要求回报文件、PR body sections 和 downstream 会形成第二事实源。	真实存在	4 个 PASS 的 完成后 块统一收敛为普通 sync 成功确认、失败停住且不手修 auto 区、只回报是否留下 待判断；测试断言旧聊天复述项不回归，并要求详情以 Full Document Reconcile 为准。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R8	用户要求举一反三	PR 提交 agent 启动语仍依赖“PASS 4 回报全部 pass ready”；Full Document Reconcile 术语没有自解释；测试中 reconcile 列名仍是硬编码字符串。	真实存在	PR 提交判断改为以 PR_BODY.md 和 final gate 为准，不以 PASS 4 聊天摘要为事实源；每个 PASS prompt 内解释 Full Document Reconcile 是文档语义对账表；测试从 FULL_RECONCILE_COLUMNS 常量反查 agent 需填写列。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R9	用户反馈	Quick Start 写“第一步打开 agent_workorder.md”，把执行 agent 的读取动作转嫁给用户，增加用户心智负担；旧整体任务句又偏向 AGENTS.md，容易和 pass owned docs 边界冲突。	真实存在	改成用户只需要复制对应 PASS code block 到新对话；说明 agent_workorder.md 是给执行 agent 的工单和机器信号，用户不阅读也不影响启动下一步；每个 PASS 保留稳定整体目标，并测试断言旧整体任务句不回归。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R10	用户原则 + Codex 复核	ready_for_next_pass 是 agent 自填弱信号，pass_handoffs 与 Full Document Reconcile 重复；新增代码只应在显著降低 agent 心智负担时保留。	真实存在	删除 pass status 数据面和 final gate 状态检查；Full Document Reconcile 成为 pass 事实源，final gate 只守 sentinel / auto / blocking status / 待补充 / template residue，待判断 交给 reviewer；同步 reviewer prompt 和 README。	README.md, scripts/sync_coding_workflow.py, scripts/sync_pr_review_system.md, scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R11	用户原则 + Codex 复核	Full Document Reconcile skeleton 默认预填 none / 待判断，等于替 agent 做语义判断。	真实存在	将 5 个 agent 语义列默认值统一改为 待补充；final gate 继续拦 待补充，测试显式写入 待判断 来验证语义不确定项仍可留给 reviewer。	scripts/sync_coding_workflow.py, tests/test_sync_coding_workflow.py
R12	用户要求 + Codex 复核	sync 仍生成两个无人读的 scratch markdown，stdout 和 workorder 仍保留旧读序 / 静态流程内容，增加 agent 和用户心智负担。	真实存在	删除 installation_status.md / full_reconcile_report.md 生成逻辑；stdout 收敛为短提示并直接给出 commit-pinned runbook URL；workorder 只保留本轮文件处理清单和 pinned OPERATIONS URL；测试断言旧文件、旧 stdout 和旧 workorder 段落不回归。	scripts/sync_coding_workflow.py, tests/test_sync_coding_workflow.py
R13	Review finding + Codex 复核	隐形 prompt 漏洞需要继续锁住：旧 workorder / stdout finding 已由 R12 修复，但 R11 的 Full Document Reconcile 默认值缺少直接回归断言。	部分过期，测试缺口真实存在	保留 workorder/stdout 负向断言，并在 skeleton 常量测试中逐行断言 5 个语义列默认全为 待补充，同时禁止旧的 `待补充	待补充
R14	用户反馈 + Claude/GPT 合意	每个 pass 的 prompt 虽然要求检查漂移，但没有把“文档缺失 / upstream 未吸收 / 代码测试行为发展”变成可验收结构。	真实存在	在 4 个 PASS prompt 中要求 Full Document Reconcile evidence 列按 class-1 template/missing、class-2 upstream、class-3 code/test/behavior drift 三段填写；未发现必须写 none。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R15	用户反馈 + Claude/GPT 合意	PASS 3 对“测试越写越冗长”的检查仍偏抽象，agent 可能需要通读 tests/，上下文消耗高。	真实存在	在 PASS 3 增加 find / grep / git log --since='3 months ago' -- tests/ 的机械信号菜单，并要求不通用时改写为项目等价命令、把实际命令写入 evidence。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py
R16	用户追问	class-1/2/3 标签本身可能不够自解释，agent 能推断但不够稳定。	真实存在	在每个 PASS prompt 内补充三类漂移定义，并用回归测试锁住定义 literal，降低跨对话执行歧义。	scripts/OPERATIONS.md, tests/test_sync_coding_workflow.py

---

最终自检

• 当前分支不是主干：codex/sync-pass-execution-contract
• 已从最新 origin/main 新建分支
• 已用 git diff --name-only origin/main...HEAD 反向核对变更范围
• 变更范围与实际 diff 一致
• 已按 TESTING.md 运行回归测试
• PR_BODY.md 仅用于更新 GitHub PR body，不纳入提交