Claw Code 2.0 Roadmap PR 合并治理机制：roadmap-pr-goals 的 Ultragoal 目标承接与 Board 工件刷新

本文围绕 docs/roadmap-pr-goals.md 讲解 Claw Code 2.0 Ultragoal 执行期间的 Roadmap PR 合并治理策略：哪些 PR 允许合并、哪些必须记录理由并转为目标（Ultragoal）工作、合并后如何刷新 Stream 0 的 CC2 board 工件。读完本文，你将掌握该治理文档的完整分诊流程、合并策略细则，以及它与 .omx/ultragoal/goals.json、.omx/ultragoal/ledger.jsonl、.omx/cc2/board.json 等 leader-owned 工件之间的调用与证据关系。

一、文档定位：把用户跟进要求固化为可追踪的治理骨架

docs/roadmap-pr-goals.md 的头部说明了它的产生背景：该文件于 2026-05-14（Asia/Seoul）在 Claw Code 2.0 Ultragoal 运行期间捕获，目的是把一条用户跟进要求"持久化"（make durable）：

所有 roadmap PR 在正确/可解决时都应被合并；未解决的 roadmap 差异（deltas）应转化为 Ultragoal 工作，而不是丢失。

文档同时声明了自己的从属关系：它是 leader-owned 的 .omx/ultragoal/goals.json 与 .omx/ultragoal/ledger.jsonl 两个工件的 tracked companion（被 git 追踪的配套文件）。这个设计意图是：治理策略本身不放在临时对话或 worker 上下文里，而是落到版本控制中，保证"不丢失"这一要求有结构性保障。

从源码结构看，这个"配套"关系并非单向声明。G011（Streams 10–12：Ecosystem/issue ops/UX）的交叉泳道验收矩阵在 docs/g011-ecosystem-ops-ux-verification-map.md 中显式列出了 "Issue/PR ops gate" 这一泳道，其 owned surface 就是 docs/pr-issue-resolution-gate.md 与 docs/roadmap-pr-goals.md，并明确了边界："Worker lanes must not merge/close remote PRs or issues; final reconciliation remains leader-owned."（worker 泳道不得合并/关闭远端 PR 或 issue，最终协调仍由 leader 拥有。）也就是说，这份治理文档同时是策略输入和验收对象：G012 最终门会检查它是否有新鲜证据，而不是假设它天然满足。

仓库中与之配套的工件结构如下：

工件	角色	说明
docs/roadmap-pr-goals.md	治理策略 + PR 分诊清单	本文主体；tracked companion
docs/pr-issue-resolution-gate.md	最终解决门（PR/Issue 全量分诊）	定义 G012 前的证据要求
docs/pr-triage-g012-final-gate.json	G012 快照账本	worker-3 捕获的 PR 调和快照
.omx/ultragoal/goals.json	目标注册表（leader-owned）	G001–G013 的状态、证据、activeGoalId
.omx/ultragoal/ledger.jsonl	追加式审计账本	每个目标事件的 JSONL 记录
.omx/cc2/board.json / .omx/cc2/board.md	Stream 0 规范 board	合并 PR 后必须刷新的覆盖率工件

二、合并策略（Merge Policy）：五条规则的逐条解读

文档的 Merge policy 一节给出五条合并规则，这是整套治理机制的核心判定逻辑：

1. 合并准入条件：只合并同时满足以下四点的 PR——仍然与 Claw Code 2.0 相关、非 draft、目标分支为 main、且在一次新鲜的 mergeability refresh 之后无冲突。注意"fresh mergeability refresh"是关键措辞：历史快照中的 MERGEABLE 状态不可复用，必须在合并前重新获取。
2. 合并方式偏好：当 GitHub 允许直接合并 PR 时，优先使用 squash merge 并附 Lore-style body（即带有上下文叙述的合并说明，而非裸标题）。
3. 纯文档 PR 的例外通道：如果一个 PR 只改文档，但它补上了一个真实的 roadmap gap，那么在 checks/冲突干净的前提下合并是可接受的。这条规则直接对应后文三张表里那批 docs(roadmap): add #NNN 类 PR。
4. 不强行合并的纪律：若 PR 已过期（stale）、被已落地工作重复、或与产品方向不对齐，则不强行合并；必须记录理由（record the rationale），并把其中仍然正确的需求映射到 G011/G012 目标中继续跟踪。
5. 合并后刷新工件：合并 roadmap PR 之后，必须刷新生成式 board 工件（.omx/cc2/board.json、.omx/cc2/board.md），让 Stream 0 的覆盖率保持最新。

第 4 条与第 5 条共同构成了"不丢失"承诺的两个方向：不能合并的需求被显式转入 Ultragoal（有理由、有归属），可以合并的需求在合并后立刻反映到 board 覆盖率上（有工件、可验证）。

配套的最终解决门 docs/pr-issue-resolution-gate.md 进一步收紧了证据标准：G012 完成审计必须使用新鲜的 GitHub 快照而非规划快照，并且要求 PR 账本"每个 PR 一行：merge / reject / defer、理由、验证、commit/merge 引用"，issue 账本"每个 issue 一行：fixed / duplicate / spam / invalid / deferred-with-rationale / externally-blocked"。该文档还明确了非目标（Non-goals）：不要求合并任何 unsafe、unverified、incompatible、spam 或 incorrect 的贡献——治理门要求的是"对一切正确且可解决的事项给出带证据的分诊与行动"，而不是无差别合并。

快照证据：治理策略如何被机器化执行

docs/pr-triage-g012-final-gate.json 展示了 G012 执行时这套策略的真实落地形态。其 source_commands 字段记录了捕获快照所用的确切命令：

gh pr list --state open --limit 100 --json number,title,headRefName,baseRefName,author,updatedAt,isDraft,mergeable,reviewDecision,statusCheckRollup,url
gh pr view <number> --json number,title,additions,deletions,changedFiles,files,commits,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,url

其中 isDraft 与 mergeable 字段直接对应合并策略第 1 条的两个硬性条件，statusCheckRollup 对应"checks 干净"的判定依据。该快照的 policy 字段写明："Merge only PRs that are correct, safe, non-conflicting…"，与治理文档逐字对齐。而 G012 的调和结论也体现了第 4 条纪律：快照中 51 个 open PR 里有 32 个处于 CONFLICTING/DIRTY 状态、19 个 MERGEABLE 但 GitHub 报告 UNSTABLE 且无新鲜 check-rollup 证据，于是 worker-3 没有执行任何合并——这正是"不强行合并、记录理由"策略的实际后果，而非失败。

三、PR 分诊清单：三类 PR 的完整继承

文档把当时开放的 roadmap PR 分成三个处置桶。原始表格中的 URL 列指向上游仓库的 PR 链接，本文省略该列，其余信息完整保留。

3.1 第一类：历史 checks 全绿、待新鲜 mergeability 确认

这一类是首批合并候选（first-pass merge candidates），前提是完成对当前 main 的新鲜 mergeability 与冲突检查：

PR	标题	分支	Checks
#2848	docs(roadmap): add #333 — no in-session settings inspect command	docs/roadmap-333-no-settings-inspect-command -> main	4/4 checks successful
#2846	docs(roadmap): add #331 — export silently overwrites on repeated invocations	docs/roadmap-331-export-filename-collision -> main	4/4 checks successful
#2869	docs(roadmap): add #358 — history entries missing role field, no pagination	docs/roadmap-348-history-entries-missing-role -> main	4/4 checks successful
#2850	docs(roadmap): add #335 — session list omits created_at_ms field	docs/roadmap-335-session-list-no-created-at -> main	4/4 checks successful
#2868	docs(roadmap): add #356 — session list title always null; no rename command	docs/roadmap-347-session-list-title-always-null -> main	4/4 checks successful
#2865	docs(roadmap): add #362 — doctor auth false-positive: misses CLI session tokens	docs/roadmap-345-doctor-auth-check-incomplete -> main	4/4 checks successful
#2864	docs(roadmap): add #364 — /cost returns no cost_usd; identical to /stats	docs/roadmap-344-cost-command-no-dollar-amount -> main	4/4 checks successful
#2867	docs(roadmap): add #368 — export always appends .txt; response.file reflects mangled path	docs/roadmap-346-export-forces-txt-extension -> main	4/4 checks successful
#2862	docs(roadmap): add #342 — status json omits active session ID, workspace counters ambiguous	docs/roadmap-342-v2 -> main	4/4 checks successful
#2876	docs(roadmap): add #354 — /cwd suggests itself in did-you-mean; self-referential loop	docs/roadmap-354-cwd-self-referential-suggestion -> main	4/4 checks successful
#2872	docs(roadmap): add #360 — /tokens, /stats, /cost identical output; no context-window or cost_usd	docs/roadmap-349-tokens-stats-cost-identical -> main	4/4 checks successful

这 11 个 PR 全部是 docs(roadmap): add #NNN 形态，即把 dogfood 中发现的行为差异（export 文件名碰撞、session list 缺字段、doctor 认证误判、/cost 无美元金额等）记录为 ROADMAP pinpoint。它们正好命中合并策略第 3 条的"纯文档但补真实 gap"通道：只要 checks 干净且无冲突即可合并，合并后由第 5 条触发 board 工件刷新。

3.2 第二类：需要本地验证或 CI 刷新

这类 PR 在 live snapshot 中没有 check rollup，合并前必须先本地验证或刷新 CI：

PR	标题	分支	Checks
#2858	docs(roadmap): add #343 — session subcommand resume-safety inconsistently enforced	docs/roadmap-340-session-resume-safe-inconsistent -> main	no checks reported
#2839	docs(roadmap): add #330 — resume mode stats/cost always zero	docs/roadmap-324-resume-stats-zero -> main	no checks reported
#2841	docs(roadmap): add #332 — doctor json missing top-level status field	docs/roadmap-325-doctor-no-status-field -> main	no checks reported
#2844	docs(roadmap): add #336 — session subcommand resume inconsistency and type/kind error mismatch	docs/roadmap-329-session-subcommand-resume-inconsistency -> main	no checks reported
#2842	docs(roadmap): add #334 — version json omits build_date and uses short sha only	docs/roadmap-328-version-json-incomplete -> main	no checks reported

值得注意的是，这 5 个"无 checks" PR 的主题集中在 session/doctor/version 的 JSON 契约缺陷上。从源码结构看，这些契约面正是 G003（boot/session 控制）与 G004（events/reports 契约族）的实施范围——goals.json 中 G003 的 evidence 列出了 status_json_surfaces_session_lifecycle_for_clawhip 等契约测试。因此这 5 个 PR 在合并时大概率会撞上"被已落地工作重复"的情形，届时就按第 4 条记录理由并映射目标，而不是机械合并。

3.3 第三类：合并前需要产品契合度（product-fit）裁决

PR	标题	分支	Checks
#2824	docs: personal assistant roadmap	pr/docs-personal-assistant-roadmap -> main	no checks reported

这个 PR 可能超出 Claw Code 2.0 roadmap 的范围，合并前需要一个产品契合度决定。它对应的内容即 docs/personal-assistant-roadmap.md——一份把"开发者 CLI agent"方向推向"个人 AI 助手（Life OS）"的路标文档，涵盖多渠道接口（chat/voice）、个人记忆（RAG）、工具/动作集成（MCP + plugins）等方向。它被单列出来正体现了合并策略第 4 条的"产品对齐"判定：方向正确但超出当前 2.0 交付边界的文档，不进入常规合并通道，而是等待显式裁决。

四、Ultragoal 映射：未解决差异如何变成目标工作

文档的最后一节定义了 roadmap 未解决项与 Ultragoal 目标体系的映射关系：

• G003–G010：当某个需求与某个 roadmap PR 标题所覆盖的实施缺口重叠、且属于活跃流（active stream）时，由对应流目标收口。
• G011：收口生态/运维/UX 类 roadmap PR，以及不属于更早流的未解决正确 issue。
• G012：最终发布门必须证明——每一个开放的 roadmap PR 要么已被合并、要么已作为 duplicate/obsolete 关闭、要么已转化为带证据的显式剩余目标（explicit remaining goal with evidence）。

这三层映射与 .omx/ultragoal/goals.json 的实际结构严格对应。该文件是 version: 1 的目标注册表，包含以下与治理机制直接相关的字段（见 .omx/ultragoal/goals.json）：

• 每个 goal 对象携带 id、title、objective、status（complete/in_progress）、attempt、startedAt/completedAt 时间戳，以及一段长 evidence 字符串——evidence 中记录了团队 ID、任务完成比（如 "5/5 tasks completed"）、推送的 commit 范围和逐条验证命令（cargo test、python3 scripts/validate_cc2_board.py 等）。
• 顶层 codexObjective 字段声明了总目标："Complete the approved Claw Code 2.0 ultragoal delivery: implement all classified ROADMAP.md backlog work through execution-sized stream goals G001-G012, using .omx/ultragoal/ledger.jsonl as the durable audit trail…"
• 顶层 activeGoalId 字段标记当前活跃目标（当前为 G013-implement-roadmap-pinpoints-693-695，状态 in_progress，其 evidence 记录了 python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json 因 3 个未映射 ROADMAP heading 失败这一事实——即治理机制在 G012 完成后仍然持续运转）。

而 G012 的 objective 把治理文档本身写进了验收条件："Final completion is blocked until docs/pr-issue-resolution-gate.md has fresh evidence showing every open PR and issue was triaged, with correct PRs merged and resolvable correct issues fixed or closed." 换言之，docs/roadmap-pr-goals.md 所定义的"不丢失"要求，最终由 G012 用可审计的工件链来证明。

审计账本：ledger.jsonl 的事件格式

与 goals.json 配套的 .omx/ultragoal/ledger.jsonl 是追加式（append-only）JSONL 账本，每行一个事件，字段为 ts（ISO 8601 时间戳）、event（plan_created/goal_started/goal_completed）、goalId、status 与 evidence。例如首行记录计划创建事件：{"ts":"2026-05-14T07:53:46.061Z","event":"plan_created","message":"279 goal(s) created"}；goal 完成事件则把完整的验证证据串写入 evidence 字段。这种"注册表 + 事件流"的双工件设计意味着：goals.json 反映当前状态（可被 leader 更新），ledger.jsonl 保留全量历史（不可篡改的审计轨迹）——治理文档声明的 leader-owned 边界正是建立在这两者之上。

五、合并后刷新 Board：Stream 0 覆盖率的机器化验证

合并策略第 5 条要求合并后刷新 .omx/cc2/board.json 与 .omx/cc2/board.md。这两个工件由 scripts/generate_cc2_board.py 从冻结的 ROADMAP.md 证据生成，并可用 scripts/validate_cc2_board.py 与 scripts/cc2_board.py 校验。理解这条规则的落地方式，需要看三个层面：

5.1 Board 条目的必备字段与枚举

生成脚本在源码层定义了 board 条目的硬约束（见 scripts/generate_cc2_board.py）：

REQUIRED_ITEM_FIELDS = [
    "id", "title", "source_anchor", "source_type", "release_bucket",
    "status", "dependencies", "verification_required", "deferral_rationale",
]
STATUSES = {
    "context", "active", "open", "done_verify", "stale_done",
    "superseded", "deferred_with_rationale", "rejected_not_claw",
}
RELEASE_BUCKETS = {
    "alpha_blocker", "beta_adoption", "ga_ecosystem",
    "post_2_0_research", "rejected_not_claw", "context", "2.x_intake",
}

每个条目必须带 source_anchor（如 ROADMAP.md:L1）指回冻结证据的具体行，deferral_rationale 字段与合并策略第 4 条的"记录理由"要求一一对应。STATUSES 中的 stale_done、superseded 等状态，正是用来承接"已合并但可能过期/被取代"的 roadmap 差异的。

5.2 当前工件的覆盖状态

.omx/cc2/board.md（schema cc2.board.v1）显示当前 board 的覆盖率证据：ROADMAP 127 个 heading、542 条有序 action 全部完成映射（127/127 PASS、542/542 PASS），共 732 个规范条目；生命周期分布上 open 285 条、done_verify 316 条、active 73 条。同文件还明确声明了变异边界："Ultragoal mutation policy: .omx/ultragoal is leader-owned and was not modified by this rendering task."——board 渲染任务可以读 ultragoal 工件，但无权写入。

.omx/cc2/board.json 的 generation_policy 字段则以机器可读形式固化了同样的约束：roadmap_coverage 为 "all markdown headings plus top-level ordered roadmap actions"，ultragoal_mutation 为 "forbidden"。

5.3 覆盖率失败的闭环案例

治理机制并非静态承诺。goals.json 中 G013 的 evidence 字段记录了一次真实的覆盖率失败闭环：在 reset 回 origin/main 之后，python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json 因 3 个未映射的 ROADMAP heading（对应 pinpoint #693–#695）而失败，于是 G013 被创建为 in_progress 目标去实施这 3 个 pinpoint。这正是"unresolved roadmap deltas should become Ultragoal work rather than being lost"这句话的机器级体现：board 校验器报出的每一个 unmapped 项，都会触发一个显式的、带证据的目标，而不是被忽略。

六、端到端证据链：一次完整治理循环的复盘

把本文涉及的工件串起来，Claw Code 2.0 的一次治理循环长这样：

1. 捕获：Ultragoal 运行期间捕获开放 PR 快照，写入 docs/roadmap-pr-goals.md 的三张分诊表（11 个绿 checks 候选、5 个待本地验证、1 个 product-fit 裁决）。

2. 分诊：按五条合并策略逐一判定；G012 执行时以 gh pr list / gh pr view 的 JSON 输出为证据输入（docs/pr-triage-g012-final-gate.json），32 个 CONFLICTING/DIRTY、19 个 UNSTABLE 的 PR 一律不合并并记录理由。

3. 转化：不能合并但需求正确的项映射到 G011/G012，或成为新的 G 目标（如 G013 承接 #693–#695），写入 .omx/ultragoal/goals.json，事件追加到 ledger.jsonl。

4. 合并与刷新：准入 PR 以 squash merge 合入 main，随后重新运行 board 生成/校验命令链刷新 Stream 0 覆盖率：

   python3 scripts/generate_cc2_board.py
   python3 scripts/validate_cc2_board.py
   python3 scripts/cc2_board.py validate
   python3 .omx/cc2/render_board_md.py .omx/cc2/board.json .omx/cc2/board.md --check
   

   （上述命令链与 G001 完成证据中记录的验证序列一致。）

5. 终局证明：G012 的最终报告 docs/g012-final-release-readiness-report.md 连同 PR 调和 JSON 一起，证明"每个开放 PR 都被 merge / close-as-duplicate / 转化为带证据的剩余目标"。

需要强调的适用前提：这套机制是 Claw Code 2.0 Ultragoal 交付过程（2026-05-14 至 2026-05-15 的 leader/worker 团队运行）的治理产物，文档中列出的 PR 号、checks 状态、快照时间均为该时点的历史记录；.omx/ 目录下的目标与 ledger 工件属于该 agent 化交付流程的内部状态，外部使用者通常只需关注 docs/ 下的治理文档与 scripts/ 下的可运行校验命令。

七、可复核要点小结

问题	判定依据	位置
一个 roadmap PR 是否可合并	四条准入条件 + checks/冲突干净	docs/roadmap-pr-goals.md
不能合并的 PR 去向	记录理由 + 映射 G011/G012	同上，Ultragoal mapping 节
最终门如何证明"不丢失"	新鲜快照 + 每 PR/issue 一行账本 + 证据	docs/pr-issue-resolution-gate.md
board 覆盖率是否达标	127/127 heading、542/542 action 全映射	.omx/cc2/board.md
目标状态与历史事件	goals.json 状态 + ledger.jsonl 追加事件	.omx/ultragoal/goals.json、.omx/ultragoal/ledger.jsonl
治理文档本身被谁验收	G011 的 Issue/PR ops gate 泳道	docs/g011-ecosystem-ops-ux-verification-map.md