ADR-003 supplement — 三阶段实施 SOP（plan / execute / verify）

§0 决策简述

决议：所有 PR（不论 Claude 还是 Codex 实施）必须显式三阶段：plan → execute → verify。每阶段有明确的产出和 gate，防范"直接动手 coding / 不写 plan / 不跑 verify"等 vibe-coding 反模式。

定位：SVA-9 九层防御的 L3 层 落地——上承 ADR-003 既定的 Claude/Codex 协作分工，下接 Archon workflow（L4）的可机读 gate 节点。借鉴 GSD（Get-Stuff-Done）范式但不引入其工具。

§1 上下文：为什么需要 SOP

Step 10-13 复盘 + Codex 实施视角 review 暴露的问题：

vibe-coding：拿到 issue 直接 coding，没先想清楚"做什么/为什么这样做/不做什么"，导致返工
plan 缺失：PR 描述往往一句话，缺乏 scope/风险点/不做什么的显式约束，review 时只能逐行扫代码
verify 走形式：只跑 npm test，不跑 contract test / invariant test / cross-section grep，问题滞后到下一个 PR 暴露
跨 Agent 接力丢失：Claude 起草的 plan 没结构化，Codex 接手时凭直觉补全，漂移

SOP 化的价值：把三个阶段固定成可机读 / 可 grep 的产出格式，让 Archon gate（L4）能自动校验"是否三阶段都到位"。

§2 SOP 三阶段定义

Phase 1 · plan（计划）

触发：issue 分配给实施 Agent（Claude 或 Codex）后立即进入。产出：PR description 中固定 5 个段落（50-200 字 / 段）：

## Plan

### 做什么
<一句话 scope，含字段/文件/模块名>

### 为什么这样做
<引用 ADR / engineering-pack / contract 锚点，说明依据>

### 不做什么（scope 外）
<明确边界，防止 scope creep>

### 风险点
<至少 1 条；与 L0.5 不变量 / L2 契约 / L7 价值姿态相关的潜在违反>

### 关联文档
<contracts/*.yaml / engineering-packs/*.md / ADR / 战略白皮书 §X>

Gate（进入 execute 的前置）：

PR description 必含上述 5 段（grep 校验）
"风险点"段不能为空
"关联文档"段至少引用 1 个 contract 或 1 个 ADR

Phase 2 · execute（实施）

触发：plan 段写完 + 自检通过。动作：写代码 + commit + push。

最小约束：

Commit message 与 plan 一致（不允许 plan 写"加 X 字段"但 commit 实际加了 X + Y）
单 PR 单一焦点（不混合 contract / 实现 / 测试的大重构）
pre-commit hook（derive:check + verify:kb）必须过

Gate（进入 verify 的前置）：

pre-commit 全绿
diff 范围与 plan §做什么一致（人 review 时 30 秒能确认）

Phase 3 · verify（自验）

触发：execute 段最后一个 commit 后，PR ready for review 之前。产出：PR description 末尾固定 verify checklist（实施 Agent 自填，逐项打勾）：

## Verify

- [ ] `npm run verify:kb` 全绿
- [ ] contract test 全过（`tests/contract_v1_*.py`）
- [ ] invariant test 全过（`tests/invariants/*.py`，L0.5 不变量映射）
- [ ] cross-section 一致性 grep 全过（contracts/ 与 engineering-packs/ 字段名一致）
- [ ] plan §不做什么 没被破坏（自检）
- [ ] plan §风险点 已逐条说明如何缓解 / 不适用
- [ ] 如涉及 V 维度（L7）相关代码，已在 PR 描述备注"待 Claude judge V1/V2/V3"

Gate（PR ready for review）：

所有 checkbox 必须勾选或显式说明 N/A
任一项失败 → PR 标 draft，不允许进入 review queue

§3 Agent 分工与三阶段的映射

阶段	Claude（战略 / 设计 / verify）	Codex（实施主力）	项目 owner（人）
plan	起草 plan 5 段（含风险点）	接手时补 plan §做什么 / §不做什么细节	大变更前 confirm plan（小变更可省）
execute	不参与（除非战略级代码）	主力（量大管饱）	不参与
verify	fresh-eyes verify（一阶 review）	自填 verify checklist	最终签字（L6）

关键不变量：

plan 段不能 Codex 单方面起草后 execute——必须有 Claude 或 owner 至少一次过目
verify 不能 self-judge——实施 Agent 自填 checklist 后，必须有另一个 Agent（alternate review）或 owner 复核

§4 触发与豁免

场景	三阶段要求
新 feature PR（如 M0 C-1）	全套 plan/execute/verify
Bug fix PR	plan 简化（50 字以内）+ execute + verify 必跑
文档 typo / 重构（无逻辑变更）	plan 段可省略；execute + verify checklist 必跑（至少 verify:kb）
Hotfix（生产事故）	plan 改为"事故描述 + 修法 + 风险"；verify 段必跑 contract test；事后补 retrospective
Spike / 探索性代码	走 branch 不走 PR；如要 merge，补全 plan/verify

§5 与 Archon workflow（L4）的衔接

Archon milestone-MN.yaml 节点设计要点：

nodes:
  - id: plan-check
    bash: 'gh pr view ${PR_NUM} --json body | jq -r .body | grep -E "^### 做什么" || exit 1'
  - id: pre-commit-gate
    bash: 'npm run verify:kb && npm run derive:check'
    depends_on: [plan-check]
  - id: contract-test
    bash: 'pytest tests/contract_v1_1.py'
    depends_on: [pre-commit-gate]
  - id: invariant-test
    bash: 'pytest tests/invariants/'
    depends_on: [pre-commit-gate]
  - id: verify-checklist
    bash: 'gh pr view ${PR_NUM} --json body | jq -r .body | grep -c "\\[x\\]" | awk "{exit (\$1 < 7)}"'
    depends_on: [contract-test, invariant-test]

上面是示意，最终 yaml 由 P0-6 落地真版本。

§6 反模式

❌ plan 写 < 50 字（如"加字段 X"）—— 等于没 plan
❌ plan 段"风险点"为空—— 隐藏未审视的风险
❌ PR 边写边改 scope—— plan 段 commit 后不允许悄悄改"做什么"，要改重开 PR
❌ verify checklist 全打勾但没真跑—— Archon gate 必须能脚本验证
❌ 跳过 verify 直接 merge—— 任何理由都不行，hotfix 也要补
❌ plan 引用模糊（"按白皮书做"）—— 必须引用 §X / 字段名 / contract 路径

§7 后果

收益：

实施前思考被强制可视化（plan 段进 git）
review 成本降低：review 者先看 plan 段，30 秒决定是否深入
跨 Agent 接力不丢信息（plan 是结构化文本）
L4 Archon gate 可自动化检查（grep + jq + exit code）
与 L0.5 / L2 / L7 联动（plan 段必引相关层产出，verify 段必跑相关测试）

成本：

每个 PR 多 5-15 分钟 plan 段时间
实施 Agent 学习曲线（5 PR 内适应）
Archon workflow yaml 复杂度上升（由 L4 承担）

§8 关联资产

ADR-003 · 工程实施栈与协作模式（本 supplement 承接 ADR-003 §"Agent 分工"）
ADR-012 · SVA-9 战略愿景对齐九层防御方案（本 supplement 是 L3 层落地物）
ADR-011 · FB-RESUME 长周期 Session 失忆防御协议
战略不变量 codify · L0.5 层（10 条核心）（L0.5 层，verify 段必须跑）
Archon workflow 契约目录（路径：.archon/workflows/，含 hello-world.yaml 真 schema 参考；不作为 Markdown 链接登记）
变更协议 · 体系级变更流程

§0 决策简述​

§1 上下文：为什么需要 SOP​

§2 SOP 三阶段定义​

Phase 1 · plan（计划）​

Phase 2 · execute（实施）​

Phase 3 · verify（自验）​

§3 Agent 分工与三阶段的映射​

§4 触发与豁免​

§5 与 Archon workflow（L4）的衔接​

§6 反模式​

§7 后果​

§8 关联资产​