[Kucell]

背景

docs/architecture/review-capability-gap-vs-pr-agent.md（PR #120）对比 Qodo v2 后确认的最小缺口：cortex 能产出经过机械校验的 review artifact，但没有出口。finding 只活在文件里，没有人在 PR 上看到它。

这是 A1，是四条能力链（生命周期 / 摘要 / 采纳率 / toolbox）的共同上游。

双仓配对

仓	PR	内容
治理仓 cortex-agent-agent	#27	8 个文件：review surface 实现 + 渲染器 + CI workflow
主仓 cortex-agent（本 PR）	—	29 个文件：L1 分发面同步 + 测试 + gitlink 推进

gitlink：1d4de9bc → 19d50601

改动

vcs-pr 新增 review surface（github backend）

操作	端点	关键点
getDiff	pulls/{n} + diff media type	默认 JSON 形态只给文件元数据、不给 hunk——reviewer 会看到"改了哪些文件"却看不到"改了什么"
listComments	issues/{n}/comments	PR 是 issue，pulls/{n}/comments 会 404
listReviews	pulls/{n}/reviews
createComment	issues/{n}/comments
submitReview	pulls/{n}/reviews	event + inline comments

CLI 新增 diff / comments / reviews / comment / review。

三条设计约束

1. comment / review 归入 GATE_USER_ONLY——它们发布到别人会读的 PR，必须 --gate user
2. backend 未实现某操作时报 capability_unavailable，不以空列表冒充"没有数据"。返回空会让调用方以为"这个 PR 没有评论没有 review"——一个 backend 从未验证过的断言
3. send() 支持额外 headers，diff media type 需要它

render-pr-comment.js（artifact → PR 评论体）

纯函数、无网络、不发明内容、字节确定。空 follow-up 不产出空章节（改为该章节不出现）；标题里的换行被压平，不能注入新的 markdown 标题；未识别的 risk 标签仍然渲染（隐藏 finding 比标签写错严重）。

顺带修掉的 collateral 问题

1. 治理仓 #23 引入的分发面漂移（8 个文件 + 2 个 schema）

#23 改了 L3 的 4 个实现文件和 2 个 schema，但没同步 L1。内容对等门禁直接报出：

• evolution-pipeline/scripts/evolve.js（+352/−17）
• knowledge-lint/scripts/index.js（+133/−19）
• management-api/scripts/index.js（±47）
• runtime-continuity/scripts/index.js（+21）
• decisions/decision.schema.json、waitpoints/waitpoint.schema.json

同步方向逐文件由 diff 证据定（都是 L3 更新）。其中 management-api 的变更带批准安全语义：Decision resolution 不再自动释放 Waitpoint。

2. _shared 层 vcs-pr 文档残缺

en 层 SKILL.md 有 update 命令、fail-closed run 关联说明等 7 个段落，_shared 层全缺——而 zh 层没有 vcs-pr，靠 _shared 兜底，zh 层项目根本发现不了 update 命令。已补齐为与 en 层同构。

3. issue-15 测试断言了已废弃的行为

原断言 decision resolve reports every auto-released waitpoint path 固化了"resolve 自动释放 Waitpoint"——而这正是 PR #69 明确废除的。已改为断言新契约，且比原来更强：验证 waitpoint 文件字节级未被修改。

验证

• 全量 484/484 passed，零 NON-HERMETIC
• 三道门禁零违规：check-l1-distribution（547 实现文件内容对等 / 364 文件集对等）/ check-l3-boundary / check-template-parity
• 本次相关测试 70 项全通过：
  • tests/review-surface/github-backend.test.js 24 项（双副本：治理仓 + L1 _shared + L1 en 各 8 项）
  • tests/review-surface/render-pr-comment.test.js 18 项（双副本各 9 项）
  • tests/guided-review/pr-review-loop.test.js 8 项（端到端，双副本各 4 项）
  • tests/agent-skills/vcs-pr-review-surface.test.js 6 项（CLI gate 与 capability 降级）

端到端实测跑通：raw findings → reviewer-backend（拒掉 1 条越界 finding）→ artifact → PR 评论 markdown。

测试做双副本的原因：内容对等门禁证明字节一致，副本测试证明行为一致——下游项目装的是 L1 副本，只跑 L3 等于没测到实际分发的代码。

已知限制

• vcs-pr update --labels 在 CLI 层未接线（index.js 的 update 分支没传 labels 给 backend），而 en 层 SKILL.md 描述了该能力。未在本次范围内修，已记录。
• 治理仓 CI 因账户级 Actions 预算耗尽未运行（job 未启动，0 steps、无 runner；真因见 check-runs/{id}/annotations）。相同测试已在主仓（public 仓，分钟不计入配额）验证通过。