refactor: 统一 PR 创建与外部绑定事实

[CodeCasterX]

问题摘要 / Issue Summary

统一 PR 创建与外部绑定事实

详细描述 / Detailed Description

定义唯一、结构化、可验证的 PR delivery/binding fact，明确区分 PR identity、绑定验证和是否由当前操作创建，并原子切换创建、发现、绑定、验证与完成流程。

相关背景 / Related Context

N/A

影响评估 / Impact Assessment

N/A

补充信息 / Additional Information

N/A

任务输入

来源

• 用户要求确认本地无重复任务后，根据 ../tmp-tasks/20260828-compat-04-pr-delivery-binding-fact.md 创建任务和 Issue。
• 原临时记录来源兼容项：C12。

已确认事实与证据

• 本地 active、blocked、completed 任务中未发现相同标题、兼容项编号或等价任务输入。
• .agents/skills/complete-task/reference/external-delivery.md 仍将 pr_status: created 定义为兼容 shim。
• lib/platform/pull-requests.ts 对新建 PR 和外部发现或绑定 PR 仍写入同一 created 状态。
• GitHub refactor: 简化 commit、create-pr 与 complete-task 流程 #906 已简化 delivery lifecycle，但明确保留该残余 shim，因此本任务是 follow-up。

约束

• 不重新引入 refactor: 简化 commit、create-pr 与 complete-task 流程 #906 已删除的 commit intent/finalization 双轨。
• 不改变 GitHub PR 本身的 open、closed、merged 状态模型。
• 不把附属平台同步失败升级为撤销已成功主动作。
• 不得通过长期双写旧 pr_status: created 与新字段过渡。
• 当前 active task 无法唯一迁移时必须失败关闭或要求显式重新绑定，不从自然语言日志猜测。

已确认决策

• 用户已确认该记录应恢复为本地受跟踪任务并级联创建 Issue。

候选与否决方案

验收标准

• 新建 PR 与绑定已有 PR 产生同一套明确、可验证的当前 delivery fact，不依赖 Activity Log 补推语义。
• complete-task 只读取结构化事实和远端验证结果，不再依赖 pr_status: created 的兼容解释。
• 所有当前 writer 与 reader 在同一变更中切换，仓库不存在旧新双写。
• 无法唯一迁移的存量任务获得明确操作指引，不被静默猜测或误判为已交付。
• taskless、prFlow=disabled、PR required 等现有策略行为保持清晰且测试通过。

未决事项

• 分析前需复核 refactor: 简化 commit、create-pr 与 complete-task 流程 #906 后 pull-requests.ts、commit-operation.ts、finalization.ts 和 complete-task gate 的最新事实流。

[CodeCasterX]

任务文件

codex · TASK-20260830-090109

元数据 (frontmatter)

---
id: TASK-20260830-090109
type: refactor
branch: agent-infra-refactor-unify-pr-delivery-fact
workflow: refactoring
status: active
created_at: 2026-08-30 09:01:09+08:00
updated_at: 2026-09-01 14:25:59+08:00
agent_infra_version: v0.9.11
priority: High
effort: High
start_date: 2026-09-01
target_date:
current_step: technical-design
assigned_to: codex
pr_status: pending
task_create_key_digest: cb417f49c6ef390a35831efc915824748ee42ae7de7abd9fd3637a697804dfda
task_create_candidate_digest: 676f543f6b5a0d4bf3e0e9eca90253d7fe3bafd77f9d53b8f9c577e96d7016be
issue_number: 929
---

任务：统一 PR 创建与外部绑定事实

描述

定义唯一、结构化、可验证的 PR delivery/binding fact，明确区分 PR identity、绑定验证和是否由当前操作创建，并原子切换创建、发现、绑定、验证与完成流程。

任务输入

来源

• 用户要求确认本地无重复任务后，根据 ../tmp-tasks/20260828-compat-04-pr-delivery-binding-fact.md 创建任务和 Issue。
• 原临时记录来源兼容项：C12。

已确认事实与证据

• 本地 active、blocked、completed 任务中未发现相同标题、兼容项编号或等价任务输入。
• .agents/skills/complete-task/reference/external-delivery.md 仍将 pr_status: created 定义为兼容 shim。
• lib/platform/pull-requests.ts 对新建 PR 和外部发现或绑定 PR 仍写入同一 created 状态。
• GitHub refactor: 简化 commit、create-pr 与 complete-task 流程 #906 已简化 delivery lifecycle，但明确保留该残余 shim，因此本任务是 follow-up。

约束

• 不重新引入 refactor: 简化 commit、create-pr 与 complete-task 流程 #906 已删除的 commit intent/finalization 双轨。
• 不改变 GitHub PR 本身的 open、closed、merged 状态模型。
• 不把附属平台同步失败升级为撤销已成功主动作。
• 不得通过长期双写旧 pr_status: created 与新字段过渡。
• 当前 active task 无法唯一迁移时必须失败关闭或要求显式重新绑定，不从自然语言日志猜测。

已确认决策

• 用户已确认该记录应恢复为本地受跟踪任务并级联创建 Issue。

候选与否决方案

验收标准

• 新建 PR 与绑定已有 PR 产生同一套明确、可验证的当前 delivery fact，不依赖 Activity Log 补推语义。
• complete-task 只读取结构化事实和远端验证结果，不再依赖 pr_status: created 的兼容解释。
• 所有当前 writer 与 reader 在同一变更中切换，仓库不存在旧新双写。
• 无法唯一迁移的存量任务获得明确操作指引，不被静默猜测或误判为已交付。
• taskless、prFlow=disabled、PR required 等现有策略行为保持清晰且测试通过。

未决事项

• 分析前需复核 refactor: 简化 commit、create-pr 与 complete-task 流程 #906 后 pull-requests.ts、commit-operation.ts、finalization.ts 和 complete-task gate 的最新事实流。

上下文

• 关联 Issue：N/A
• 关联 PR：N/A
• 分支：agent-infra-refactor-unify-pr-delivery-fact

需求

Brainstorming

• status: done
• question_count: 0
• pending_question:
• answered:

分析

需求分析报告（Round 1）

受影响的文件

• path/to/file1 - 变更描述
• path/to/file2 - 变更描述

需求分析报告（Round 2）

需求分析报告（Round 3）

设计

技术方案（Round 1）

技术方案（Round 2）

技术方案（Round 3）

技术方案（Round 4）

技术方案（Round 5）

实现备注

[实现阶段的备注。做出的决策、权衡、与设计的偏差。]

审查反馈

需求分析审查（Round 1）

需求分析审查（Round 2）

需求分析审查（Round 3）

技术方案审查（Round 1）

技术方案审查（Round 2）

技术方案审查（Round 3）

技术方案审查（Round 4）

审查分歧账本

id	stage	round	severity	status	evidence
AN-1	analysis	3	major	closed	review-analysis-r3.md#AN-1
AN-2	analysis	3	major	closed	review-analysis-r3.md#AN-2
HD-1	plan	-	decision	human-decided	task.md#HDR-1
PL-1	plan	3	major	closed	review-plan-r3.md#PL-1
PL-2	plan	2	major	closed	review-plan-r2.md#PL-2
PL-3	plan	2	minor	closed	review-plan-r2.md#PL-3
PL-4	plan	4	major	closed	review-plan-r4.md#PL-4
PL-5	plan	5	major	accepted	plan-r5.md#PL-5: 新增必填且与 PullRequestResult.status/result 正交的 creationOutcome，穷尽 planned/not-created/created/reused/no-op/unknown，并逐项固定 dry-run、前置失败、明确 POST 失败、retryable unknown、POST 成功后绑定失败和正常路径的组合。

人工裁决

HDR-1

• 原账本 ID：HD-1
• 裁决时间：2026-09-01 12:54:34+08:00
• 裁决结果：A

实现输入

id	ledger_id	decision_evidence	stage	needs_implementation	decided_at	status	consumed_by

工作流告警

id	time	step	severity	code	status	target	message	action	resolved_at	resolution

活动日志

• 2026-08-30 09:01:09+08:00 — Create Task [started] by codex — started
• 2026-08-30 09:01:09+08:00 — Create Task by codex — Task created from structured candidate
• 2026-09-01 00:02:32+08:00 — Analyze Task (Round 1) [started] by codex — started
• 2026-09-01 00:07:07+08:00 — Analyze Task (Round 1) by codex — Analysis completed → analysis.md
• 2026-09-01 00:12:32+08:00 — Review Analysis (Round 1) [started] by codex — started
• 2026-09-01 00:23:57+08:00 — Review Analysis (Round 1) by codex — Verdict: Changes Requested, blockers: 0, major: 2, minor: 0, Manual-validation: 0 → review-analysis.md
• 2026-09-01 08:24:54+08:00 — Analyze Task (Round 2) [started] by codex — started
• 2026-09-01 08:28:55+08:00 — Analyze Task (Round 2) by codex — Analysis completed → analysis-r2.md
• 2026-09-01 09:15:49+08:00 — Review Analysis (Round 2) [started] by codex — started
• 2026-09-01 09:19:56+08:00 — Review Analysis (Round 2) by codex — Verdict: Changes Requested, blockers: 0, major: 2, minor: 0, Manual-validation: 0 → review-analysis-r2.md
• 2026-09-01 11:01:56+08:00 — Analyze Task (Round 3) [started] by codex — started
• 2026-09-01 11:05:15+08:00 — Analyze Task (Round 3) by codex — Analysis completed → analysis-r3.md
• 2026-09-01 11:17:14+08:00 — Review Analysis (Round 3) [started] by codex — started
• 2026-09-01 11:22:59+08:00 — Review Analysis (Round 3) by codex — Verdict: Approved, blockers: 0, major: 0, minor: 0, Manual-validation: 0 → review-analysis-r3.md
• 2026-09-01 11:25:44+08:00 — Plan Task (Round 1) [started] by codex — started
• 2026-09-01 11:31:18+08:00 — Plan Task (Round 1) by codex — Plan completed, awaiting human review → plan.md
• 2026-09-01 11:34:03+08:00 — Review Plan (Round 1) [started] by codex — started
• 2026-09-01 11:42:18+08:00 — Review Plan (Round 1) by codex — Verdict: Changes Requested, blockers: 0, major: 2, minor: 1, Manual-validation: 0 → review-plan.md
• 2026-09-01 11:54:11+08:00 — Plan Task (Round 2) [started] by codex — started
• 2026-09-01 12:00:56+08:00 — Plan Task (Round 2) by codex — Plan completed, awaiting human review → plan-r2.md
• 2026-09-01 12:03:14+08:00 — Review Plan (Round 2) [started] by codex — started
• 2026-09-01 12:08:07+08:00 — Review Plan (Round 2) by codex — Verdict: Changes Requested, blockers: 0, major: 1, minor: 0, Manual-validation: 0 → review-plan-r2.md
• 2026-09-01 12:54:34+08:00 — Human Decision by human — HD-1 decided → HDR-1
• 2026-09-01 12:55:22+08:00 — Plan Task (Round 3) [started] by codex — started
• 2026-09-01 13:03:28+08:00 — Plan Task (Round 3) by codex — Plan completed, awaiting human review → plan-r3.md
• 2026-09-01 14:02:29+08:00 — Review Plan (Round 3) [started] by codex — started
• 2026-09-01 14:07:38+08:00 — Review Plan (Round 3) by codex — Verdict: Changes Requested, blockers: 0, major: 1, minor: 0, Manual-validation: 0 → review-plan-r3.md
• 2026-09-01 14:09:30+08:00 — Plan Task (Round 4) [started] by codex — started
• 2026-09-01 14:11:40+08:00 — Plan Task (Round 4) by codex — Plan completed, awaiting human review → plan-r4.md
• 2026-09-01 14:15:14+08:00 — Review Plan (Round 4) [started] by codex — started
• 2026-09-01 14:19:11+08:00 — Review Plan (Round 4) by codex — Verdict: Changes Requested, blockers: 0, major: 1, minor: 0, Manual-validation: 0 → review-plan-r4.md
• 2026-09-01 14:20:35+08:00 — Plan Task (Round 5) [started] by codex — started
• 2026-09-01 14:25:59+08:00 — Plan Task (Round 5) by codex — Plan completed, awaiting human review → plan-r5.md

完成检查清单

• 所有需求已满足
• 测试已编写并通过
• 代码已审查
• 文档已更新（如适用）
• PR 已创建

产物生命周期收据

event	output	input	input_sha256	completed_at
review-analysis.completed	review-analysis.md	analysis.md	b3e7cd263688025de95739b69f554ea91d5f88705126c78a22ed8d33f74301f8	2026-09-01 00:23:57+08:00
review-analysis.completed	review-analysis-r2.md	analysis-r2.md	83bb4864a5836c12a99036e67fd5f78b0e51ecdc1c81ab6e9486e3ee2118fb8d	2026-09-01 09:19:56+08:00
review-analysis.completed	review-analysis-r3.md	analysis-r3.md	8d89a51e1f21a44867ac526e4add87bcee318ffc9e27b17fb700514795ef5b08	2026-09-01 11:22:59+08:00
review-plan.completed	review-plan.md	plan.md	bfb46ef0a6529494305123a5914906eb02f72f7e179414fb6a861cf47e09f174	2026-09-01 11:42:18+08:00
review-plan.completed	review-plan-r2.md	plan-r2.md	1d6626ac9e9c5e02fd906969ba3938e591a5c72701540bae483a7bbbd2b23832	2026-09-01 12:08:07+08:00
review-plan.completed	review-plan-r3.md	plan-r3.md	2816fb2298470db1517cfacaafc70984fe5807a330225d650f38bb59e81e3d6e	2026-09-01 14:07:38+08:00
review-plan.completed	review-plan-r4.md	plan-r4.md	2c1a873883a0a64d45e378c4a22f569fa2d6a565305d2fb4e376bf6a273c2f99	2026-09-01 14:19:11+08:00

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

需求分析（Round 1）

codex · TASK-20260830-090109

需求分析报告

• 分析轮次：Round 1
• 产物文件：analysis.md

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f 5473 task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md

• 2026-08-30 09:01:09+08:00 — Create Task by codex — Task created from structured candidate

完成检查清单

• 所有需求已满足
• 测试已编写并通过
• 代码已审查
• 文档已更新（如适用）
• PR 已创建

需求来源

来源类型：用户描述 + GitHub Issue #929
来源摘要：

任务要求统一 PR 创建、已有 PR 绑定、外部 PR 发现、绑定验证和完成校验所使用的持久化事实。该事实必须区分 PR identity、绑定是否经过验证，以及 PR 是否由当前操作创建；所有 writer/reader 应一次性切换，不保留旧新双写。Issue #929 与任务输入内容一致。

需求理解

当前任务不是新增一条 PR 状态，而是收敛交付事实的来源和语义：创建 PR、复用已有 PR、显式绑定已有 PR、从 Issue 发现外部已合并 PR，都应产生同一套结构化且可验证的 delivery/binding fact。该 fact 需要同时保存足以复核远端 PR 身份的证据、绑定验证结果，以及当前操作是否实际创建了 PR。complete-task 及其 required-PR/终态校验必须直接消费该结构化事实和远端验证结果，不再把 pr_status: created 当作“已绑定/已交付”的兼容解释。

范围还包括任务创建模板、PR 平台操作的 typed result、所有 PR identity 消费者、完成门禁、双语技能文档和相关测试。现有 checkpoint commit、宿主 finalization 顺序、GitHub 的 open/closed/merged 模型及附属平台同步的 warning 语义需要保持不变。

相关文件

• lib/platform/pull-requests.ts:424-442 - 读取任务 PR identity；bindIdentity 在 :669-687 将创建和绑定统一写为 pr_status: created，而 resolveExternalPullRequest 在 :737-849 也写入相同状态并追加外部绑定审计；创建/复用流程位于 :851-976。
• lib/internal/platform-pr.ts:16-22,64-133 - 暴露 inspect、bind、resolve-external、create、sync 和 summary-sync 的 typed CLI 边界，需随事实结果变化同步校验。
• lib/task/create.ts:185-224 - 新任务 frontmatter 的 PR 初始字段 writer；当前在 :215 写入 pr_status: pending。
• .agents/templates/task.md:1-20 - 本地任务模板中的 PR 字段契约；templates/.agents/templates/task.en.md:1-20 与 templates/.agents/templates/task.zh-CN.md:1-20 是发布模板副本。
• lib/task/verification-engine.ts:490-545 - required-pr-delivery 完成/预完成门禁，当前按 pr_status 与 pr_number 判定策略并验证远端合并状态。
• lib/platform/verification-required.ts:35-108 - required checks 门禁，当前以 pr_status/pr_number 决定是否跳过及读取远端 PR checks。
• lib/platform/pr-summary.ts:67-73,106-136 - PR 摘要上下文和评论同步读取 pr_number。
• lib/platform/pr-checks.ts:120-130 - PR checks/readiness 读取任务绑定的 PR identity。
• lib/platform/verification-sync.ts:154-159,323-345 - 平台同步验证按任务 PR identity 决定 PR 评论校验路径。
• lib/pr-review/evidence-grading.ts:62-99 - PR 审查证据宿主候选按 pr_number 与 Issue 反查任务，需避免继续依赖旧字段形态。
• lib/task/human-override.ts:607-620,695-720 - 人工覆盖探针定位 PR 资源，属于 identity 的非主流程消费者。
• lib/task/commit-operation.ts:286-475 - 当前 checkpoint commit、推送和 task metadata 同步边界；未直接读写 PR 状态，需确保改造不重新引入已删除的 commit/finalization 双轨。
• lib/task/finalization.ts:592-729 - 按 preflight → lifecycle → task comment → terminal verification 顺序收尾；PR 事实由验证器消费，需保持该原子生命周期边界。
• .agents/skills/complete-task/SKILL.md:61-103,155-191 与 .agents/skills/complete-task/reference/external-delivery.md:1-17 - 完成前置条件、外部交付和 pr_status: created 兼容说明；英文/中文模板副本也需同步。
• .agents/skills/create-pr/SKILL.md:14-26,67-99 - 创建/复用/绑定结果和任务状态写回契约，需改为新的事实边界。
• tests/integration/cli/platform-pr.test.ts:78-133,184-236、tests/integration/cli/complete-task-preflight.test.ts:44-129、tests/integration/cli/complete-task-remote-evidence.test.ts - 创建、外部绑定、完成前置和重放行为的集成覆盖。
• tests/unit/core/pr-status-contract.test.ts:1-108、tests/unit/core/requires-pr-gating.test.ts:1-108、tests/integration/cli/task-verify.test.ts:46-104 - 当前绑定 pr_status 契约和 required-PR gate 的测试，需要整体切换而不是新增双轨断言。
• tests/unit/platform/pr-summary.test.ts、tests/unit/platform/pr-checks.test.ts、tests/unit/pr-review/evidence-grading.test.ts、模板测试 - identity 消费者、审查候选和双语模板的回归覆盖。

影响评估

直接影响：

• 任务 frontmatter/模板的 PR delivery schema 与默认状态。
• platform-pr 的 create、reuse、bind、resolve-external 原子写入，以及返回给 CLI/技能的 typed result。
• required-pr-delivery 和 required-checks/终态验证对 delivery fact 的读取、远端身份复核和 prFlow 三态策略判定。
• complete-task、create-pr 及 external-delivery 文档、配置和测试契约。

间接影响：

• PR 摘要、checks、平台同步、PR 审查证据和人工覆盖流程都需要从统一 identity accessor/fact 获取 PR 编号或资源身份。
• task-finalization 仍须保持生命周期完成后再做终态验证；平台同步失败仍只能形成 warning，不得回滚成功的主动作。
• 现有 active/completed 任务 fixture、Issue 同步评论内容和模板完整性测试会受到 schema 迁移影响。
• commit-operation 的 checkpoint intent 与 delivery target 不是 PR delivery fact，不能被合并成第二条生命周期或因本次重构重新引入旧的 commit intent/finalization 双轨。

技术风险

• 持久化 schema 迁移风险：旧任务可能只有 pr_status: created、pr_number 或自然语言日志，无法唯一推导创建来源或验证证据。按兼容性规则应采用 current-only；无法唯一解释时失败关闭并给出显式重新绑定/修复指引，不能静默猜测，也不能长期双写。
• 远端副作用与重放风险：PR 创建成功但任务写回或附属同步失败时不能删除或假装未发生。新事实必须支持依据远端身份恢复、区分 created/reused，并在锁内原子写回；重放应为可验证 no-op。
• 外部 PR 身份风险：外部绑定的 PR 可能来自 fork，必须保留 Issue closing relationship、PR/base/head repository/ref/SHA、合并时间和 merge commit 等可验证信息；多候选、身份冲突或证据缺失必须继续 fail closed。
• 策略回归风险：prFlow=required、prFlow=disabled、配置缺省及显式跳过的行为现在由 pr_status 参与判定。切换时若把“是否需要 PR”和“是否绑定了 PR”混为一谈，会错误放行或阻断完成流程。
• 消费面遗漏风险：生产读取点分布在平台、验证、审查和人工覆盖模块，测试还包含模板/文档契约。只改 create/bind writer 会留下隐性旧 reader，形成事实漂移。
• 双语/测试漂移风险：技能说明和三份任务模板均属于发布契约；删除旧字段时需要同步删除专属旧测试与 fixture，避免用反向删除断言维持旧概念。

依赖关系

• parseTaskFrontmatter/writeTask 提供任务事实的解析和原子更新边界；新 schema 必须能被现有 frontmatter 读写及版本戳机制一致处理。
• platform-pr 依赖平台 adapter、GitHub Issue closing PR 查询、PR inspection 和任务执行锁；创建、绑定、外部发现需要共享同一身份验证语义。
• complete-task 的 preflight 与 task-finalization 的 terminal verification 依赖 verification-engine；两处不能各自解释 delivery 状态。
• prFlow 配置、远端 GitHub PR/Issue API、任务分支 SHA 和 required checks 是验证事实的外部输入；网络/权限失败必须保持 blocked 或 warning 的现有分层。
• create-pr、complete-task 及其英文/中文模板、配置和测试是用户可见契约，需与 runtime 一次性同步。

假设

• 当前 HEAD（包含 refactor: 简化 commit、create-pr 与 complete-task 流程 #906/refactor(lifecycle): 简化交付生命周期流程 #908 之后的简化生命周期和 refactor(cli): 重构提交检视与目标分支闭环  #940 的 checkpoint/delivery 改动）是实现基线；本任务不恢复已删除的 commit intent/finalization 双轨。
• pr_number 当前主要承载远端 PR identity，pr_status 承载粗粒度流程状态；本报告不预先决定新 fact 的字段命名或是否将 identity 嵌套保存，该选择留给技术方案阶段。
• GitHub Issue refactor: 统一 PR 创建与外部绑定事实 #929 的正文没有补充 task.md 之外的新验收标准；本报告以 task.md 的“任务输入”和验收标准为准。

未决问题

• 技术方案需要确定结构化 delivery/binding fact 的精确 schema、字段命名、必填证据和 reader 访问边界，并明确“identity / binding verified / created by current operation”三类语义如何独立表示。
• 技术方案需要定义旧 active/completed 任务的识别和操作指引：哪些旧记录可明确失败关闭，哪些必须要求显式 bind/重新验证；不得从 Activity Log 自然语言推导创建来源。
• 需要在方案/实现阶段确认删除 pr_status 后 prFlow 缺省、required、disabled 和显式跳过的状态机表示，确保没有新旧字段并行写入。

工作量和复杂度评估

• 复杂度：高
• 风险等级：高

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

需求分析审查（Round 1）

codex · TASK-20260830-090109

需求分析审查报告

• 审查轮次：第 1 轮
• 产物文件：review-analysis.md
• 审查输入：
  • analysis.md

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f	9976	analysis.md
f	5745	task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md
- 2026-09-01 00:07:07+08:00 — **Analyze Task (Round 1)** by codex — Analysis completed → analysis.md

## 完成检查清单

- [ ] 所有需求已满足
- [ ] 测试已编写并通过
- [ ] 代码已审查
- [ ] 文档已更新（如适用）
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

审查摘要

• 审查者：codex
• 审查时间：2026-09-01 00:19:12+08:00
• 审查范围：analysis.md、task.md、GitHub Issue refactor: 统一 PR 创建与外部绑定事实 #929，以及 PR fact 的 runtime、workflow、skill 和测试消费面
• 总体结论：需要修改
• 发现（AI 可处理）：0 阻塞项，2 主要，0 次要 / 人工校验：0

检视覆盖声明

pass_id	scope	evidence	result	gaps_or_assumptions
pass-1	任务来源、Issue、分析正文与当前代码事实	task.md:24-70、analysis.md:24-105、platform-issue inspect、PR 字段全仓检索	任务目标、约束、兼容方向与 Issue 一致	原始临时记录已不在 ../tmp-tasks/；以已持久化的 task/Issue 输入为来源
pass-2	来源到需求、验收、影响、风险的追踪	analysis.md:30-100、下方追踪矩阵与验收矩阵	需求和风险主干存在，但验收没有可观察闭环，消费面清单不完整	形成 2 条 major finding
pass-3	风险镜头	.agents/rules/compatibility-policy.md、analysis.md:73-80	命中 compatibility-budget；current-only、禁止双写和失败关闭方向合规	未新增兼容预算，无期限/退出条件不适用
pass-4	对候选问题寻找反证	analysis.md:36-55、task.md:60-66 与全仓 rg 结果	原始验收条目和大量文件清单不能替代可执行验收；检索确认仍有未列出的直接 reader/contract	若方案阶段重新全仓扫描，仍无法弥补分析阶段缺少设计输入的问题
pass-5	finding、manual-validation、advisory 与 verdict 收敛	本报告问题清单、专项覆盖与证据原文	2 条 major，0 条人工校验，结论为需要修改	无待人工裁决；schema 命名属于后续方案细节

lens_id	trigger_evidence	loaded	result
compatibility-budget	analysis.md:75 讨论旧 schema、存量任务、current-only 与失败关闭；task.md:51-52 禁止双写和自然语言猜测	yes	未申请兼容预算；一次性切换、保留原数据并给出显式恢复指引符合策略
documentation-antipatterns	analysis 阶段不适用	not-applicable	该镜头仅适用于 code 阶段
testing-discipline	analysis 阶段不适用	not-applicable	该镜头仅适用于 code 阶段；本轮仅检查测试范围与验收可验证性
security-risks	analysis 阶段不适用	not-applicable	该镜头仅适用于 code 阶段；安全角色风险另在专项覆盖中检视
migration-risks	analysis 阶段不适用	not-applicable	该镜头仅适用于 code 阶段；schema 迁移作为 compatibility-budget 的当前需求检视
concurrency-risks	analysis 阶段不适用	not-applicable	该镜头仅适用于 code 阶段；原子写回与锁语义已作为质量属性检视
cross-platform-risks	analysis 阶段不适用	not-applicable	该镜头仅适用于 code 阶段，来源也未提出 OS 行为变化

需求分析专项覆盖

perspective_id	applicability	reviewed_scope	evidence	result_or_gap
user	applicable	同一 delivery fact、显式失败指引、策略行为	task.md:60-66、analysis.md:30-34,73-80	covered
maintainer	applicable	单一事实源、依赖、兼容性与长期维护面	analysis.md:36-55,75-80、全仓 PR 字段检索	gap：直接 reader、workflow 与 skill 契约未完整枚举，见 finding-2
operations	applicable	远端副作用恢复、重放、网络/权限失败分层	analysis.md:69,76,85-88	covered
security	applicable	fork/head/base/SHA 身份、授权与失败关闭	analysis.md:77,85-87	covered
testing	applicable	输入、动作、结果、边界与验证环境	analysis.md:53-55,78-80、task.md:60-66	gap：没有逐项可执行的验收闭环，见 finding-1

quality_id	source	stakeholder	priority_or_tradeoff	verification	result_or_gap
QA-identity	SRC-TASK	user, security	高；不得以粗粒度状态代替身份验证	对 create/reuse/bind/external 分支比较持久化 identity 与远端证据	covered
QA-atomicity	SRC-TASK	maintainer, operations	高；主动作成功不得被附属同步回滚	注入写回/同步失败并验证可恢复、可重放且无双事实源	covered
QA-compat-current-only	SRC-TASK	maintainer	高；禁止长期双写，未知旧数据失败关闭	对 ambiguous legacy fixture 验证保留数据、停止写入和操作指引	covered
QA-testability	SRC-TASK	testing	高；五条验收须可观察闭环	逐项给出输入、动作、预期结果和验证层级	gap：见 finding-1

evolution_id	source	confirmation_status	classification	boundary_evidence	result_or_gap
EV-legacy-task	SRC-TASK	confirmed	design-input	task.md:51-52,65 只要求一次性切换或显式重新绑定，不授权长期兼容	covered
EV-schema-shape	SRC-ANALYSIS	unconfirmed	open-question	analysis.md:93,98 明确不在分析阶段锁定嵌套方式或字段命名	covered

acceptance_id	observable_input	action	expected_result	status_or_gap
AC-1	新建 PR、复用 PR、显式绑定 PR、外部发现 PR 四类任务	执行各 typed intent 并检查结果与持久化任务事实	使用同一规范 fact；identity/verified/current-operation-created 语义可独立判定，且无需读 Activity Log	gap：分析未定义分支级观察点与判定方式
AC-2	仅含旧 pr_status: created 的任务与含新 fact 的任务	分别运行 complete-task preflight/terminal verification	旧 shim 不被当作已交付；新 fact 必须结合远端验证通过	gap：分析未定义正反 fixture 和预期 gate 结果
AC-3	全仓所有 PR fact writer/reader	检索并执行相关单元、集成和 e2e 测试	writer/reader 原子切换且无旧新双写	gap：分析影响清单遗漏直接消费者，见 finding-2
AC-4	可唯一识别与不可唯一识别的存量任务	执行迁移/重新绑定入口	唯一记录按规范转换；歧义记录保留原数据、失败关闭并返回明确指引	gap：分析未定义可唯一识别的边界和可验证输出
AC-5	prFlow 缺省、required、disabled、taskless 与显式 skip 组合	运行策略矩阵测试	保持来源约束规定的放行/阻断行为，且不再依赖旧 created shim	gap：分析只列分支名称，未给出矩阵期望

追踪矩阵

source_id	upstream	reviewed_target	verification	status_or_gap
SRC-TASK	task.md:24-70 的目标、约束与五条验收	analysis.md:30-100 的理解、影响、风险、假设与未决问题	逐条对照 + 上述 AC-1..AC-5	gap：验收未操作化
SRC-ISSUE	GitHub Issue #929 正文	analysis.md:24-34,94	agent-infra-internal platform-issue inspect TASK-20260830-090109	covered；Issue 未增加额外验收
SRC-CODE-WRITERS	pull-requests.ts、create.ts、任务模板	analysis.md:38-41,61-64	`rg -n "pr_status	pr_number"`
SRC-CODE-READERS	runtime、workflow、skill、测试中的 PR fact 消费者	analysis.md:42-55,66-71	全仓 rg 与定点 nl	gap：见 finding-2
SRC-COMPAT	现有 created shim 与 ambiguous legacy tasks	analysis.md:75,80,93,98-100	compatibility policy 四项准入检查	covered；采用 current-only，无新增兼容预算

问题清单

阻塞项（必须修复）

（无）

主要问题（建议修复）

finding-1：五条来源验收没有转换为可执行的验收契约

文件：analysis.md:90
场景：后续方案需要判断 create/reuse/bind/external、旧任务迁移以及 prFlow 各策略分支是否满足需求时，当前报告只能回看 task.md 的概括性验收句，无法从分析产物取得稳定 acceptance ID、可观察输入、验证动作和预期结果。
影响：方案和测试可能各自解释“明确、可验证”“行为保持清晰”等措辞，遗漏负向分支或把结构 gate 通过误当成语义正确；需求无法稳定追踪到测试。
证据：rg -n "^## |验收|acceptance_id|observable_input|expected_result" analysis.md 显示报告在 ## 假设 后直接进入未决问题和工作量，没有验收章节或验收字段；task.md:60-66 的五条上游验收也未在 analysis.md 中逐项操作化。
置信度：high
未验证假设：无。
修复方向：在下一轮分析中为五条来源验收建立稳定 ID，并逐条补齐可观察输入、动作、预期结果、正反分支与验证层级；至少覆盖四类 PR 获得路径、legacy 唯一/歧义、prFlow 三态、taskless 和 skip。

finding-2：影响范围清单遗漏仍直接读取旧 PR 字段的契约和消费点

文件：analysis.md:36
场景：若方案按报告的“相关文件”形成原子切换清单，仍有 workflow、watch/commit skill 契约、post-review gate 和 e2e required-checks fixture 直接读取或规定 pr_status/pr_number，却未被分析列为具体影响项。
影响：实现可能在同一变更后留下旧 reader 或旧文档契约，直接违反“所有当前 writer 与 reader 同一变更切换”的验收，并造成 workflow 进度、watch-pr、post-review 完成门禁或 required checks 行为漂移。
证据：定点检索确认 .agents/workflows/refactoring.yaml:6、.agents/skills/watch-pr/SKILL.md:42-43,77、.agents/skills/commit/reference/task-status-update.md:61、lib/task/verification-engine.ts:1113 和 tests/e2e/core/validate-artifact-required-checks.test.ts:21,47,129,160 都直接消费旧字段；同一组路径/token 在 analysis.md 中无匹配。
置信度：high
未验证假设：新 fact 的最终 schema 尚未决定；即使保留 pr_number，这些位置仍需被方案显式分类为“保持 identity 字段”或“切换 accessor”，而不能从影响清单消失。
修复方向：以全仓字段/语义检索建立 writer、runtime reader、workflow/skill contract、template/fixture/test 四类消费矩阵；逐项标记 replace、retain-with-rationale 或 delete，并把遗漏项纳入测试基线。

次要问题（低影响但需闭环）

（无）

非阻塞建议

（无）

人工校验项

（无）

审查分歧账本回写

• 新 finding 1：finding-upsert --stage analysis --ordinal 1 --severity major --evidence review-analysis.md#finding-1
• 新 finding 2：finding-upsert --stage analysis --ordinal 2 --severity major --evidence review-analysis.md#finding-2
• 无上一轮 finding 响应需要复核；无 needs-human-decision。

证据原文

• 断言：分析产物未提供可执行验收章节或字段。

$ rg -n "^## |验收|acceptance_id|observable_input|expected_result" .agents/workspace/active/TASK-20260830-090109/analysis.md
6:## 状态核对
15:## 完成检查清单
24:## 需求来源
30:## 需求理解
36:## 相关文件
57:## 影响评估
73:## 技术风险
82:## 依赖关系
90:## 假设
94:- GitHub Issue #929 的正文没有补充 task.md 之外的新验收标准；本报告以 task.md 的“任务输入”和验收标准为准。
96:## 未决问题
102:## 工作量和复杂度评估

• 断言：分析未列出一组仍直接消费旧 PR 字段的 runtime、workflow、skill 与 e2e 位置。

$ if rg -n "workflows/refactoring|watch-pr|commit/reference/task-status-update|verification-engine\.ts:1113|validate-artifact-required-checks" .agents/workspace/active/TASK-20260830-090109/analysis.md; then :; else echo '(no matches)'; fi
(no matches)
$ rg -n "pr_status|pr_number" .agents/workflows/refactoring.yaml .agents/skills/watch-pr/SKILL.md .agents/skills/commit/reference/task-status-update.md lib/task/verification-engine.ts tests/e2e/core/validate-artifact-required-checks.test.ts
.agents/workflows/refactoring.yaml:6:# 字段缺省时仅当 task.md 的 `pr_status=skipped` 排除，否则计入（详见 .agents/skills/complete-task/SKILL.md）。
.agents/skills/watch-pr/SKILL.md:42:- 场景 A（省略入参）：从当前分支反查 active task；定位后读取其 `pr_number`。
.agents/skills/watch-pr/SKILL.md:43:- 场景 B（省略 task ref 或 `--task/-t`，**任务锚定主路径**）：按「任务上下文解析」取得完整 `{task-id}`。读 `.agents/workspace/active/{task-id}/task.md` 取 `pr_number` 作为 `{pr#}`；`pr_number` 为空时按「错误处理」提示先 `create-pr`，停止。
.agents/skills/watch-pr/SKILL.md:77:- **不改** `pr_status`（保持 `created`）与 `current_step`
.agents/skills/commit/reference/task-status-update.md:61:- [ ] 所有工作流步骤已完成（对 yaml `commit` 步骤的 `pr_tasks` 列表，按「走 PR 路径」判定是否计入：`prFlow=required` 始终计入；`prFlow=disabled` 不计入；缺省下仅当 `pr_status=skipped` 时不计入，否则计入）
lib/task/verification-engine.ts:1113:  const hasPullRequest = Number(task.metadata.pr_number) > 0;
tests/e2e/core/validate-artifact-required-checks.test.ts:21:    metadata: { id: "TASK-20260101-000001", pr_number: 42, last_reviewed_commit: SHA },
tests/e2e/core/validate-artifact-required-checks.test.ts:47:  assert.equal(evaluate({ metadata: { id: "TASK-20260101-000001", pr_number: 42, last_reviewed_commit: "b".repeat(40) } }).status, "fail");
tests/e2e/core/validate-artifact-required-checks.test.ts:129:    metadata: { id: "TASK-20260101-000001", pr_number: 42 },
tests/e2e/core/validate-artifact-required-checks.test.ts:160:        return { ok: true, metadata: { id: "TASK-20260101-000001", pr_number: 42 } };

• 断言：Issue refactor: 统一 PR 创建与外部绑定事实 #929 与 task.md 的目标、约束和五条验收一致，未增加新验收。

$ agent-infra-internal platform-issue inspect TASK-20260830-090109
status=no-op; issue=#929; state=open; title="refactor: 统一 PR 创建与外部绑定事实"; body mirrors task input and acceptance criteria

• 断言：兼容镜头命中，但分析选择 current-only、禁止双写、歧义失败关闭，未申请兼容预算。

$ nl -ba .agents/workspace/active/TASK-20260830-090109/analysis.md | sed -n '73,100p'
73  ## 技术风险
75  - **持久化 schema 迁移风险**：旧任务可能只有 `pr_status: created`、`pr_number` 或自然语言日志，无法唯一推导创建来源或验证证据。按兼容性规则应采用 current-only；无法唯一解释时失败关闭并给出显式重新绑定/修复指引，不能静默猜测，也不能长期双写。
80  - **双语/测试漂移风险**：技能说明和三份任务模板均属于发布契约；删除旧字段时需要同步删除专属旧测试与 fixture，避免用反向删除断言维持旧概念。
93  - `pr_number` 当前主要承载远端 PR identity，`pr_status` 承载粗粒度流程状态；本报告不预先决定新 fact 的字段命名或是否将 identity 嵌套保存，该选择留给技术方案阶段。
98  - 技术方案需要确定结构化 delivery/binding fact 的精确 schema、字段命名、必填证据和 reader 访问边界，并明确“identity / binding verified / created by current operation”三类语义如何独立表示。
99  - 技术方案需要定义旧 active/completed 任务的识别和操作指引：哪些旧记录可明确失败关闭，哪些必须要求显式 `bind`/重新验证；不得从 Activity Log 自然语言推导创建来源。
100 - 需要在方案/实现阶段确认删除 `pr_status` 后 `prFlow` 缺省、required、disabled 和显式跳过的状态机表示，确保没有新旧字段并行写入。

自我质疑

• 未直接核验分析中关于 refactor: 简化 commit、create-pr 与 complete-task 流程 #906、refactor(lifecycle): 简化交付生命周期流程 #908、refactor(cli): 重构提交检视与目标分支闭环  #940 历史提交关系的断言；本轮 findings 不依赖这些历史编号是否准确。若其历史关系被推翻，需要修订背景说明，但不影响验收操作化和消费面缺口。
• 原始 ../tmp-tasks/20260828-compat-04-pr-delivery-binding-fact.md 当前不存在；task.md 与 Issue refactor: 统一 PR 创建与外部绑定事实 #929 已保存完整任务输入，因此本轮以两者为上游来源。若临时记录曾含未持久化要求，需要另行补回来源后再复审。

亮点

• 正确识别该任务是事实源收敛而非新增 PR 状态，并保持 refactor: 简化 commit、create-pr 与 complete-task 流程 #906 后的 lifecycle 边界。
• 对 ambiguous legacy task、远端副作用、重放、fork identity、策略回归和消费面遗漏均给出了方向正确的风险判断。
• 明确拒绝长期双写与自然语言日志推断，兼容方向符合 current-only 策略。

与方案一致性

• 实现与技术方案一致（尚未进入方案/实现阶段）
• 没有意外的范围扩张

结论与建议

审查决定

• 通过
• 需要修改
• 拒绝

下一步

补充可执行验收矩阵和完整 PR fact 消费面清单后，重新执行需求分析审查。

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

需求分析（Round 2）

codex · TASK-20260830-090109

需求分析报告

• 分析轮次：Round 2
• 产物文件：analysis-r2.md

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f 9976 analysis.md
f 18103 review-analysis.md
f 6499 task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md

• 2026-09-01 00:23:57+08:00 — Review Analysis (Round 1) by codex — Verdict: Needs Changes, blockers: 0, major: 2, minor: 0 / Manual-validation: 0, Human-decision: 0 → review-analysis.md

需求来源

来源类型：用户描述 + GitHub Issue #929
来源摘要：

任务要求统一 PR 创建、已有 PR 绑定、外部 PR 发现、绑定验证和完成校验所使用的持久化事实。该事实必须区分 PR identity、绑定是否经过验证，以及 PR 是否由当前操作创建；所有 writer/reader 应一次性切换，不保留旧新双写。Issue #929 与任务输入内容一致。

对上一轮审查的响应

• AN-1 / finding-1：accepted。已核实上一轮证据：analysis.md 没有 acceptance ID 或“可观察输入—动作—预期结果”矩阵，而 task.md 的五条验收仍是概括性条目。本轮新增 ## 可执行验收矩阵，以 AC-1 至 AC-5 分别覆盖四类 PR 获得路径、完成门禁、全量 writer/reader 切换、存量任务歧义处理和 prFlow/taskless/skip 策略；每项均列输入、动作、预期结果、正反分支和验证层级。
• AN-2 / finding-2：accepted。已按审查报告重新 Read/Grep 核实遗漏：.agents/workflows/{feature-development,bug-fix,refactoring}.yaml、.agents/skills/watch-pr/SKILL.md、.agents/skills/commit/reference/task-status-update.md、lib/task/verification-engine.ts:1113 和 tests/e2e/core/validate-artifact-required-checks.test.ts 确实仍规定或消费 PR 字段。本轮新增 ## PR fact 消费面矩阵，并把这些路径与上一轮已列出的 runtime、技能、模板、测试入口分成 writer、reader、workflow/skill contract、fixture/test 四类；方案阶段必须逐项标记 replace、retain-with-rationale 或 delete。

需求理解

当前任务是收敛 PR 交付事实的语义和唯一来源，不是为 pr_status 增加更多取值。新建 PR、复用精确匹配的已有 PR、显式绑定已有 PR、从 Issue 唯一发现或显式选择外部已合并 PR，都必须产生同一套结构化且可验证的 delivery/binding fact。该 fact 要独立表达远端 PR identity、绑定验证证据/结果，以及 PR 是否由本次操作创建；完成流程不得通过 Activity Log 或 pr_status: created 反推这些语义。

切换必须覆盖所有生产 writer、reader、workflow/skill contract、模板和测试 fixture。prFlow=required、prFlow=disabled、配置缺省、显式 skip、taskless 以及附属平台 warning 的既有策略边界仍需保持清晰。checkpoint commit、宿主 finalization 的固定顺序和 GitHub PR 的 open/closed/merged 模型不在本任务中重新定义。

相关文件

相关代码、模板、工作流、技能契约和测试入口已按 writer、reader、workflow/skill contract、template、fixture/test 分组列于下方 ## PR fact 消费面矩阵；该矩阵即为方案阶段的完整切换清单。

PR fact 消费面矩阵

类别	当前入口	当前事实使用	本任务必须确认的切换边界
Writer	lib/task/create.ts:185-224、.agents/templates/task.md:1-20、templates/.agents/templates/task.{en,zh-CN}.md:1-20	创建任务时写入 pr_status: pending	新任务只产生当前规范的 delivery fact 初始形态；不得写旧 pr_status 作为并行事实源
Writer	lib/platform/pull-requests.ts:655-687,737-849,851-976	create/reuse、显式 bind、external bind 都写 pr_number 与 pr_status: created；外部路径另外记录身份审计	三类动作共用一个原子 fact writer；created-by-current-operation 必须来自动作结果而非日志推断；远端失败、竞态和重放保持 fail-closed/no-op 语义
CLI boundary	lib/internal/platform-pr.ts:16-22,64-133	暴露 create、bind、resolve-external、inspect、sync 和 summary-sync typed result	typed result 应能让调用方区分 identity、binding verification 和 create provenance；下游不得重新解析文本日志
Core reader	lib/task/verification-engine.ts:490-545	required-pr-delivery 按 pr_status/pr_number 做策略与合并验证；:1096-1155 的 post-review gate 按 pr_number 进入 PR 等价性验证	preflight、terminal verification 和 post-review gate 必须读取同一 fact/access boundary；旧 shim 单独存在时不能放行
Core reader	lib/platform/verification-required.ts:35-108	required checks 按 pr_status/pr_number 决定跳过、检查和 PR head 关系	不能把“项目是否要求 PR”“任务是否绑定 PR”“远端检查是否通过”压缩为一个状态；策略矩阵必须保持原语义
Platform readers	lib/platform/pr-summary.ts:67-136、lib/platform/pr-checks.ts:120-130、lib/platform/verification-sync.ts:154-159,323-345	PR 摘要、checks、评论/Issue 同步按 pr_number 定位远端资源	保留的 identity 使用必须通过规范 fact 读取；缺失或身份不完整时保持现有错误/跳过分层
Review/override readers	lib/pr-review/evidence-grading.ts:62-99、lib/task/human-override.ts:607-620,695-720	反查 task 或人工探针按 pr_number 定位 PR	需明确哪些只需要 identity、哪些需要已验证 binding；人工覆盖不能用旧字段补造身份或创建来源
Workflow contracts	.agents/workflows/feature-development.yaml:5-6、.agents/workflows/bug-fix.yaml:5-6、.agents/workflows/refactoring.yaml:5-6	commit/pr_tasks 是否计入当前依赖 pr_status=skipped	改为当前 fact/策略契约后，三类工作流必须一致；不能遗留只认旧字段的进度规则
Skill contracts	.agents/skills/complete-task/SKILL.md:61-103,155-191、reference/external-delivery.md:1-17、.agents/skills/create-pr/SKILL.md:14-26,67-99、.agents/skills/watch-pr/SKILL.md:38-81、.agents/skills/commit/reference/task-status-update.md:53-72，以及双语副本	文档规定 pr_status 状态机、外部 PR shim、watch-pr 保持 created 和提交后的 PR 路径	文档、命令输入和运行时必须同一版本切换；不得保留无期限旧字段说明或让技能重新解释 Activity Log
Test contracts	tests/unit/core/pr-status-contract.test.ts、tests/unit/core/requires-pr-gating.test.ts、tests/integration/cli/platform-pr.test.ts、tests/integration/cli/task-verify.test.ts、tests/integration/cli/complete-task-preflight.test.ts、tests/integration/cli/complete-task-remote-evidence.test.ts	固化旧模板字段、create/bind/external 行为和 required-PR gate	替换为正向 fact/策略行为测试；覆盖主动作失败、重放、身份冲突和旧输入 fail-closed，不以“旧字符串不存在”作为唯一测试目标
Test consumers	tests/e2e/core/validate-artifact-required-checks.test.ts、tests/e2e/core/validate-artifact-platform-sync.test.ts、tests/integration/cli/platform-checks.test.ts、tests/unit/platform/{pr-summary,pr-checks}.test.ts、tests/unit/pr-review/evidence-grading.test.ts、模板完整性测试	用 pr_number/pr_status 构造 checks、sync、审查候选和模板 fixture	fixture 必须表达 fact 的必要字段及策略状态，避免测试继续暗示旧字段是 canonical truth

lib/task/commit-operation.ts:286-475 当前负责 checkpoint commit、推送和 task metadata 同步，不直接读写 PR fact；lib/task/finalization.ts:592-729 负责 preflight → lifecycle → task comment → terminal verification 的固定顺序。二者是本任务的流程边界，需验证切换后仍只有验证器消费 PR fact，不能借重构重新引入已删除的 commit/finalization 双轨。

可执行验收矩阵

ID	可观察输入	动作	预期结果（含反向分支）	验证层级
AC-1	新建 PR、精确复用已有 PR、显式绑定已有 PR、Issue 唯一/显式选择外部已合并 PR 四类场景	通过 typed platform-pr intent 执行并读取持久化 fact 与 typed result；不读取 Activity Log 推断	四类场景产生同一规范 fact；identity 字段与远端快照一致；binding verification 只有在精确验证成功后成立；created-by-current-operation 仅在实际 POST 创建时为真，复用/绑定/外部发现为假。缺字段、身份竞态或多候选必须失败关闭且不写入错误事实；相同完整证据重放为 no-op	pull-requests 单元测试 + platform-pr 集成测试；GitHub API 使用 fake client
AC-2	仅有旧 pr_status: created/旧 PR 字段的任务、结构化 fact 完整但远端未合并/身份不匹配的任务、结构化 fact 与远端合并身份均有效的任务	执行 complete-task.preflight、required-PR gate 和 terminal verification	旧 shim 不能单独授权完成；结构化 fact 缺失/畸形或远端身份不匹配时 fail/blocked；只有 fact 与远端验证同时满足时才按项目策略通过；post-review PR 等价性继续使用真实远端证据	verification-engine、verification-required 单元/e2e + complete-task 集成测试
AC-3	全仓 writer、runtime reader、workflow/skill contract、template/fixture/test 清单	执行静态消费矩阵审查并运行完整测试	所有当前 writer/reader 在同一变更中归一到规范 fact；不存在生产路径对旧 pr_status: created 的 canonical 解释或新旧双写；每个保留的 identity 读取都有明确理由；文档、模板和 fixture 与 runtime 一致	rg/代码审查作为范围验证；模板契约、单元、集成和 e2e 测试作为行为验证
AC-4	可唯一验证的存量记录、只有旧粗粒度字段的记录、旧字段与审计/远端证据冲突或多重候选的记录	通过明确的迁移/重新绑定入口处理，或直接运行完成/绑定验证	可唯一验证的记录按当前规范转换并留下完整证据；无法唯一解释的记录保留原数据、停止写入并返回显式修复/重新绑定指引；不得从自然语言 Activity Log 推测创建来源，不得静默标记为已交付	迁移/绑定集成 fixture、错误路径测试和 task 状态不变性检查
AC-5	prFlow 缺省、required、disabled，以及 taskless、显式 skip、已绑定 PR 的组合	运行 commit/workflow 下一步、complete-task preflight/terminal verification 和 taskless 操作	required 必须有规范且已验证的 PR delivery fact，skip 不能绕过；disabled 不进入 PR 路径；缺省策略保留现有 create-or-explicit-skip 语义；taskless 仍遵守 task context 边界；附属同步失败只形成 warning，不撤销主动作	workflow/skill 契约测试、required-pr/required-checks e2e、complete-task 集成测试

影响评估

直接影响：

• task frontmatter schema、任务创建 writer 和三份发布模板。
• platform-pr create/reuse/bind/resolve-external 的持久化写回、typed result 和重放/竞态行为。
• required-PR、required-checks、post-review PR 等价性和 complete-task 终态验证。
• PR 摘要、checks、平台同步、PR 审查证据、人工覆盖和 watch/commit/workflow 文档契约。
• 覆盖上述路径的 unit/integration/e2e/template 测试及存量 fixture。

间接影响：

• task-finalization 的固定生命周期顺序和 Issue/task 评论同步的 warning/pending 投影。
• 远端 GitHub Issue closing PR 查询、fork/base/head/SHA 身份证据和 required checks API。
• 现有 active/completed 任务的存量解释与明确恢复指引；未知状态必须保留数据并停止写入。

技术风险

• schema 与存量任务风险：旧字段无法证明创建来源或 binding 验证时，必须 current-only、fail closed；一次性转换只能位于明确边界，不能在业务核心长期维护两套状态。
• 远端副作用风险：PR 创建成功后任务写回、评论或附属同步可能失败；必须保留主动作事实，依据远端身份恢复并把外围失败降为 warning，不能删除或误报。
• 身份与授权风险：外部 PR 可能来自 fork，且 Issue 可能对应多个 closing PR；base/head repository/ref/SHA、合并时间、merge commit 和授权来源必须可独立校验。
• 策略回归风险：将 PR 是否必需、是否已绑定、是否验证通过和是否由本次创建混为一个状态，会在 required/disabled/default/skip 分支中造成错误放行或阻断。
• 消费面遗漏风险：字段读取分散于验证、同步、审查、人工覆盖和技能契约；任一遗漏都会留下事实漂移。
• 测试/文档漂移风险：双语模板、工作流注释和旧契约测试会继续把 pr_status 暗示为真相源；需要用正向行为测试替换，而非增加反向删除断言。

依赖关系

• parseTaskFrontmatter/writeTask 的结构化解析和原子写回能力。
• platform-pr 的平台 adapter、GitHub API、任务执行锁和远端 Git SHA 复核。
• verification-engine、required checks adapter 以及 task-finalization 的 preflight/terminal 调用顺序。
• .agents/.airc.json 的 prFlow 策略、任务分支 delivery target 和远端 Issue/PR/checks 数据。
• create-pr、complete-task、watch-pr、commit/workflow 文档与其英文/中文模板副本。

假设

• 当前 HEAD（包含 refactor: 简化 commit、create-pr 与 complete-task 流程 #906/refactor(lifecycle): 简化交付生命周期流程 #908 之后的生命周期简化和 refactor(cli): 重构提交检视与目标分支闭环  #940 的 checkpoint/delivery 改动）是实现基线；本任务不恢复已删除的 commit intent/finalization 双轨。
• pr_number 可能仍作为远端 identity 的组成信息被保留，但其最终存储位置、是否嵌套以及 fact 字段命名属于技术方案阶段决策；本报告不预先选型。
• Issue refactor: 统一 PR 创建与外部绑定事实 #929 与 task.md 的任务输入和验收标准一致；原始临时记录不作为额外、未持久化需求来源。

未决问题

• 技术方案需要确定规范 fact 的最终 schema、必填证据、访问边界和 typed result 对应关系。
• 技术方案需要确定旧 active/completed 任务的显式迁移/重新绑定入口及可唯一验证的边界；不能把 Activity Log 自然语言作为创建来源证据。
• 方案需要把 prFlow 策略与 delivery fact 的独立语义映射成完整状态矩阵，并确认 taskless 与显式 skip 的边界行为。

工作量和复杂度评估

• 复杂度：高
• 风险等级：高

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

需求分析审查（Round 2）

codex · TASK-20260830-090109

需求分析审查报告

• 审查轮次：第 2 轮
• 产物文件：review-analysis-r2.md
• 审查输入：
  • analysis-r2.md

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f	14760	analysis-r2.md
f	9976	analysis.md
f	18103	review-analysis.md
f	7175	task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md
- [ ] 代码已审查
- [ ] 文档已更新（如适用）
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

## 产物生命周期收据

| event | output | input | input_sha256 | completed_at |
| --- | --- | --- | --- | --- |
| review-analysis.completed | review-analysis.md | analysis.md | b3e7cd263688025de95739b69f554ea91d5f88705126c78a22ed8d33f74301f8 | 2026-09-01 00:23:57+08:00 |

审查摘要

• 审查者：codex
• 审查时间：2026-09-01 09:16:58+08:00
• 审查范围：analysis-r2.md、task.md、Issue refactor: 统一 PR 创建与外部绑定事实 #929、上一轮 2 条 finding 响应，以及 PR fact 的 runtime/workflow/skill/test 消费面
• 总体结论：需要修改
• 发现（AI 可处理）：0 阻塞项，2 主要，0 次要 / 人工校验：0

检视覆盖声明

pass_id	scope	evidence	result	gaps_or_assumptions
pass-1	独立读取修订稿、任务来源和当前代码/契约	analysis-r2.md:17-114、task.md:24-70、全仓 PR 字段检索	修订稿显著补强验收与消费面，但仍有可复现缺口	先形成候选问题，再读取 task.md:120-121 的 accepted 响应
pass-2	来源—验收—影响—风险追踪及上一轮 finding 响应	analysis-r2.md:23-64、下方追踪与验收矩阵	AN-1/AN-2 均已部分修复，尚不足以关闭	无新独立 finding；对原 finding 补证后保持 open
pass-3	compatibility-budget 风险镜头	.agents/rules/compatibility-policy.md、analysis-r2.md:60-64,82-89	current-only、显式转换/重新绑定、禁止双写方向合规	未授权长期兼容；期限/退出条件不适用于 current-only 路径
pass-4	对“已完整覆盖”主动反证	rg 直接消费者、complete-task/SKILL.md:77-84	找到未列入矩阵的 skill/rule reader，以及 AC-5 未覆盖的 --force 分支	这些证据直接推翻“全部类别/完整状态矩阵”声明
pass-5	finding、人工校验、裁决与 verdict 收敛	本报告 AN-1/AN-2 复核块	0 新 finding；AN-1、AN-2 补证后维持 open；0 人工校验/裁决	第二轮仍低于默认三轮握手上限，无需升级人工裁决

lens_id	trigger_evidence	loaded	result
compatibility-budget	analysis-r2.md:63,84 涉及旧 schema、显式转换、current-only 与 fail closed	yes	未新增/延长 shim；一次性显式转换与歧义失败关闭符合策略
documentation-antipatterns	analysis 阶段不适用	not-applicable	注册表限定 code 阶段
testing-discipline	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；本轮只审查测试范围输入
security-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；安全角色另行覆盖
migration-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；迁移需求由兼容镜头覆盖
concurrency-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；原子写回/重放作为质量属性覆盖
cross-platform-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段，来源未触发 OS 行为变化

需求分析专项覆盖

perspective_id	applicability	reviewed_scope	evidence	result_or_gap
user	applicable	单一 fact、明确恢复指引、策略行为	task.md:60-66、analysis-r2.md:28-32,56-64	gap：AC-5 未完整表达既有 override/taskless 结果，见 AN-1
maintainer	applicable	writer/reader、兼容、长期契约与切换范围	analysis-r2.md:38-54、全仓 rg	gap：直接 skill/rule reader 仍遗漏，见 AN-2
operations	applicable	远端副作用、重放、warning、恢复	analysis-r2.md:60,63-64,78-80,84-85	covered
security	applicable	fork、身份、授权、多候选、fail closed	analysis-r2.md:60-61,79,86	covered
testing	applicable	输入、动作、结果、正反分支和验证层级	analysis-r2.md:56-64	gap：AC-5 的 --force 与 taskless 预期仍不足以形成完整状态矩阵

quality_id	source	stakeholder	priority_or_tradeoff	verification	result_or_gap
QA-identity	SRC-TASK	user, security	高；identity/verified/provenance 独立	四类 PR 路径的 typed result、持久化 fact 与远端快照对照	covered
QA-atomicity	SRC-TASK	maintainer, operations	高；主动作不可被附属同步回滚	写回/同步故障注入与重放 no-op	covered
QA-compat-current-only	SRC-TASK	maintainer	高；禁止长期双写和日志猜测	legacy 唯一/歧义 fixture 与数据不变性检查	covered
QA-policy-preservation	SRC-TASK	user, testing	高；现有 PR 流程策略不得漂移	prFlow/skip/force/taskless 组合矩阵	gap：见 AN-1
QA-scope-completeness	SRC-TASK	maintainer	高；所有 reader/writer 同变更切换	全仓语义检索与逐项 replace/retain/delete 分类	gap：见 AN-2

evolution_id	source	confirmation_status	classification	boundary_evidence	result_or_gap
EV-legacy-task	SRC-TASK	confirmed	design-input	task.md:51-52,65 与 analysis-r2.md:63,84 限定显式转换/重新绑定或失败关闭	covered
EV-schema-shape	SRC-ANALYSIS-R2	unconfirmed	open-question	analysis-r2.md:102,107 将字段命名/存储位置留给方案，不扩张为当前已确认需求	covered

acceptance_id	observable_input	action	expected_result	status_or_gap
AC-1	create/reuse/bind/external 四类路径	typed intent + fact/result/远端快照核对	同一 fact，三类语义独立，错误 fail closed，重放 no-op	verifiable
AC-2	old shim、畸形/不匹配 fact、完整且远端有效 fact	preflight、required-PR、terminal verification	旧 shim 不授权；无效 fail/blocked；有效按策略通过	verifiable
AC-3	writer/reader/contract/template/test 清单	静态矩阵审查 + 完整测试	同变更切换且无 canonical 旧解释/双写	gap：消费清单未完整，见 AN-2
AC-4	可验证、粗粒度、冲突/多候选 legacy 记录	显式迁移/重新绑定或验证	唯一记录转换；歧义保留数据、停止写入并给出指引	verifiable
AC-5	prFlow 三态、taskless、skip、已绑定组合	workflow/commit/complete/taskless 操作	策略边界保持	gap：未覆盖 --force；taskless 只写“遵守边界”，未给出可观察的允许/拒绝结果

追踪矩阵

source_id	upstream	reviewed_target	verification	status_or_gap
SRC-TASK	task.md:24-70 的目标、约束与验收	analysis-r2.md:28-109	逐条对照 AC-1..AC-5、影响和风险	gap：现有策略“等”仍有 force/taskless 缺口
SRC-ISSUE	GitHub Issue #929	analysis-r2.md:17-21,103	platform-issue inspect	covered；未发现额外验收
SRC-AN-1	review-analysis.md#finding-1	analysis-r2.md:25,56-64	矩阵形状 + complete-task 当前策略反证	partial；补证后维持 open
SRC-AN-2	review-analysis.md#finding-2	analysis-r2.md:26,38-54	全仓字段检索 + 路径逐项反查	partial；补证后维持 open
SRC-COMPAT	旧 created shim 与 legacy records	analysis-r2.md:60-64,82-89,107-109	compatibility policy	covered；current-only，无长期兼容预算

问题清单

阻塞项（必须修复）

（无）

主要问题（建议修复）

AN-1：验收矩阵仍未覆盖完整既有策略分支

文件：analysis-r2.md:64
场景：prFlow 缺省且任务未绑定 PR 时，维护者以 --force 执行 complete-task，或 taskless 操作进入允许/拒绝分支；AC-5 只列 taskless/skip/已绑定组合，并以“遵守 task context 边界”概括 taskless 结果。
影响：方案和测试无法从验收输入唯一确定 --force 在缺省与 required 策略下的不同权限，也无法验证各 taskless 操作究竟应允许、拒绝还是降级；切换 fact 时可能意外扩大或收紧现有策略。
证据：rg -n "force|taskless|skip|AC-5" analysis-r2.md 没有任何 force 命中，AC-5 的 taskless 预期仅为“遵守 task context 边界”；.agents/skills/complete-task/SKILL.md:81-84 明确 --force 可越过缺省 pending 和其他前置条件，但不能解除 prFlow=required 强约束。
置信度：high
未验证假设：未逐项枚举所有 taskless-capable intent；这不影响 --force 缺口本身，补充时应按实际入口限定，不扩张为所有 PR 操作都支持 taskless。
修复方向：在 AC-5 增加 --force × prFlow 的正反预期，并把 taskless 拆成实际适用入口及其可观察允许/拒绝/无任务副作用结果。

AN-2：消费面矩阵仍遗漏直接读取 PR identity 的 skill/rule 契约

文件：analysis-r2.md:38
场景：方案把该矩阵当作“完整切换清单”逐项处理时，complete-manual-validation、commit PR summary、review-code 出口、review-pr 任务反查和 task-management 的 create-pr 状态约定仍直接读取/规定 pr_number，但矩阵没有列出这些路径。
影响：若 identity 存储位置或 accessor 改变，这些用户可见流程可能继续读取旧 frontmatter；即使最终保留 pr_number，也缺少 retain-with-rationale 分类，无法证明“所有 writer/reader 同变更切换”。
证据：路径反查对六个直接契约均输出 missing；定点 rg 显示 .agents/skills/complete-manual-validation/SKILL.md:60、其 reference/summary-update.md:3、.agents/skills/commit/reference/pr-summary-sync.md:3、.agents/skills/review-code/reference/output-templates.md:25、.agents/skills/review-pr/reference/evidence-grading.md:20,36 和 .agents/rules/task-management.md:52 直接使用或规定 pr_number。
置信度：high
未验证假设：pr_number 可能作为规范 fact 的 identity 组成继续保留；但报告自己要求每个保留 reader 明确理由，因此这些路径仍必须进入矩阵接受 retain/replace 分类。
修复方向：把所有直接命中补入 workflow/skill/rule contract 类，并逐项注明 replace、retain-with-rationale 或 delete；用同一检索结果复核没有未分类命中。

次要问题（低影响但需闭环）

（无）

非阻塞建议

（无）

人工校验项

（无）

审查分歧账本回写

• AN-1：执行方响应为 accepted；复核后以补充证据维持 open，evidence → review-analysis-r2.md#AN-1。
• AN-2：执行方响应为 accepted；复核后以补充证据维持 open，evidence → review-analysis-r2.md#AN-2。
• 本轮无新 finding，无 needs-human-decision。

证据原文

• 断言：AC-5 未提及 --force，且 taskless 预期未落到可观察结果；当前 complete-task 明确存在 force 的策略差异。

$ rg -n "force|taskless|skip|AC-5" .agents/workspace/active/TASK-20260830-090109/analysis-r2.md
25:- **AN-1 / finding-1：accepted**。…覆盖…`prFlow`/taskless/skip 策略…
32:切换必须覆盖…配置缺省、显式 skip、taskless…
64:| AC-5 | `prFlow` 缺省、`required`、`disabled`，以及 taskless、显式 skip、已绑定 PR 的组合 | … | …taskless 仍遵守 task context 边界… |
87:- **策略回归风险**：…required/disabled/default/skip 分支…
109:- 方案需要…确认 taskless 与显式 skip 的边界行为。
$ nl -ba .agents/skills/complete-task/SKILL.md | sed -n '77,85p'
77  | `disabled` | 任意 | 无 PR 路径 → PR 维度满足，继续其余前置条件 |
78  | `required` | `created` | PR 维度满足，继续 |
79  | `required` | `pending` / `skipped` | **停止**：强制 PR 下必须先 `/create-pr`；`--skip-pr` 不被接受… |
80  | 缺省 | `created` / `skipped` | PR 维度满足，继续 |
81  | 缺省 | `pending` | **默认停止**…除非用户提供 `--skip-pr`…或 `--force` |
83  - `--skip-pr` 处理：仅在 `prFlow` 非 `required` 时生效…
84  - 注：`--force` 可越过下方其余前置条件，但**不解除 `prFlow=required` 的 PR 强约束**…

• 断言：修订稿宣称完整的消费面矩阵仍缺少六个直接 PR identity 契约。

$ for p in '.agents/skills/complete-manual-validation/SKILL.md' '.agents/skills/complete-manual-validation/reference/summary-update.md' '.agents/skills/commit/reference/pr-summary-sync.md' '.agents/skills/review-code/reference/output-templates.md' '.agents/skills/review-pr/reference/evidence-grading.md' '.agents/rules/task-management.md'; do if rg -F "$p" .agents/workspace/active/TASK-20260830-090109/analysis-r2.md >/dev/null; then echo "listed $p"; else echo "missing $p"; fi; done
missing .agents/skills/complete-manual-validation/SKILL.md
missing .agents/skills/complete-manual-validation/reference/summary-update.md
missing .agents/skills/commit/reference/pr-summary-sync.md
missing .agents/skills/review-code/reference/output-templates.md
missing .agents/skills/review-pr/reference/evidence-grading.md
missing .agents/rules/task-management.md
$ rg -n "pr_number|pr_status" .agents/skills/complete-manual-validation/SKILL.md .agents/skills/complete-manual-validation/reference/summary-update.md .agents/skills/commit/reference/pr-summary-sync.md .agents/skills/review-code/reference/output-templates.md .agents/skills/review-pr/reference/evidence-grading.md .agents/rules/task-management.md
.agents/rules/task-management.md:52:- `create-pr`：更新 `pr_number`、`updated_at`、`agent_infra_version`
.agents/skills/commit/reference/pr-summary-sync.md:3:仅当 `{task-id}` 有效且 `task.md` 存在有效 `pr_number` 时执行；否则跳过。
.agents/skills/complete-manual-validation/reference/summary-update.md:3:…仅在有效 `{task-id}` 且 task.md 已绑定 `pr_number` 时执行…
.agents/skills/review-pr/reference/evidence-grading.md:20:…本地 `active/*/task.md` 的 `pr_number` 命中优先于 `issue_number` 反查…
.agents/skills/review-pr/reference/evidence-grading.md:36:- 对齐 = freshness 为 fresh 且 `issue_number` / `pr_number` 与解析结果一致。
.agents/skills/review-code/reference/output-templates.md:25:…再读取任务的 `prFlow` / `pr_number`；存在 PR 时调用…
.agents/skills/complete-manual-validation/SKILL.md:60:- 有效 PR：优先使用显式 `{pr-ref}`，否则读取 task.md frontmatter 的 `pr_number`

• 断言：AN-1/AN-2 当前均为第二轮 accepted 响应，尚待 reviewer 回交。

$ nl -ba .agents/workspace/active/TASK-20260830-090109/task.md | sed -n '118,122p'
118 | id | stage | round | severity | status | evidence |
119 |----|-------|-------|----------|--------|----------|
120 | AN-1 | analysis | 2 | major | accepted | 已核实…analysis-r2.md#可执行验收矩阵… |
121 | AN-2 | analysis | 2 | major | accepted | 已核实…analysis-r2.md#PR-fact-消费面矩阵… |

自我质疑

• 未直接核验 refactor: 简化 commit、create-pr 与 complete-task 流程 #906/refactor(lifecycle): 简化交付生命周期流程 #908/refactor(cli): 重构提交检视与目标分支闭环  #940 的历史关系；本轮结论不依赖这些编号是否准确。
• 未把所有 pr_number 测试 fixture 逐条列为遗漏，因为修订稿已按测试类别覆盖；AN-2 只坚持可证明未进入矩阵的用户可见 skill/rule 契约。
• taskless 适用入口需要执行方按当前 typed context 逐项确认；本轮只判定“遵守边界”不可作为验收预期，不预设具体入口集合。

亮点

• AC-1 至 AC-4 已把主要输入、动作、正反结果和验证层级闭环，显著改善上一轮可测试性缺口。
• writer、核心 reader、平台 reader、review/override reader、workflow 和主要测试类别已形成清晰分组。
• schema 迁移继续坚持 current-only、显式恢复和数据不变性，兼容边界方向正确。

与方案一致性

• 实现与技术方案一致（尚未进入方案/实现阶段）
• 没有意外的范围扩张

结论与建议

审查决定

• 通过
• 需要修改
• 拒绝

下一步

补齐 AC-5 的 force/taskless 可观察分支，并将剩余直接 PR identity skill/rule 契约纳入消费面矩阵后，重新执行需求分析审查。

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

需求分析（Round 3）

codex · TASK-20260830-090109

需求分析报告

• 分析轮次：Round 3
• 产物文件：analysis-r3.md

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f 14760 analysis-r2.md
f 9976 analysis.md
f 17131 review-analysis-r2.md
f 7247 task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md

• PR 已创建

产物生命周期收据

event	output	input	input_sha256	completed_at
review-analysis.completed	review-analysis.md	analysis.md	b3e7cd263688025de95739b69f554ea91d5f88705126c78a22ed8d33f74301f8	2026-09-01 00:23:57+08:00
review-analysis.completed	review-analysis-r2.md	analysis-r2.md	83bb4864a5836c12a99036e67fd5f78b0e51ecdc1c81ab6e9486e3ee2118fb8d	2026-09-01 09:19:56+08:00

需求来源

来源类型：用户描述 + GitHub Issue #929
来源摘要：

任务要求统一 PR 创建、已有 PR 绑定、外部 PR 发现、绑定验证和完成校验使用的持久化事实。该事实必须区分 PR identity、绑定是否经过验证，以及 PR 是否由当前操作创建；所有 writer/reader 应一次性切换，不保留旧新双写。Issue #929 与任务输入一致。

对上一轮审查的响应

• AN-1 / finding-1：accepted。已核实 review-analysis-r2.md#AN-1 的证据：analysis-r2.md 的 AC-5 没有 --force，且 taskless 结果只有“遵守 task context 边界”。定点读取 .agents/skills/complete-task/SKILL.md:71-84,167 确认：disabled 不进入 PR 路径，required 的 pending/skipped 不能被 --force 绕过，缺省 pending 可由 --force 越过，但身份、失败/阻塞和 required-PR hard gate 仍不可绕过。定点读取 .agents/skills/commit/SKILL.md:18-25,74-84 确认当前可验证的 taskless 入口是 direct commit；本轮 AC-5 增加了可观察的 force 矩阵和该入口的允许、拒绝及无副作用结果，未把 taskless 能力泛化到未有契约证据的 PR 操作。
• AN-2 / finding-2：accepted。已核实 review-analysis-r2.md#AN-2 的六个遗漏路径及其 pr_number 命中：complete-manual-validation 主文档与摘要更新 reference、commit PR summary reference、review-code 出口、review-pr 证据分级 reference、.agents/rules/task-management.md。本轮在消费面矩阵中逐项补入，并为每项标明 replace 或 retain-with-rationale；同时保留全仓语义检索作为方案阶段的未分类命中门禁。

需求理解

当前任务是收敛 PR 交付事实的语义和唯一来源，不是为 pr_status 增加更多取值。新建 PR、复用精确匹配的已有 PR、显式绑定已有 PR、从 Issue 唯一发现或显式选择外部已合并 PR，都必须产生同一套结构化且可验证的 delivery/binding fact。该 fact 要独立表达远端 PR identity、绑定验证证据/结果，以及 PR 是否由本次操作创建；完成流程不得通过 Activity Log 或 pr_status: created 反推这些语义。

切换必须覆盖所有生产 writer、reader、workflow/skill/rule contract、模板和测试 fixture。prFlow=required、prFlow=disabled、配置缺省、显式 skip、complete-task --force、当前有证据的 taskless commit，以及附属平台 warning 的策略边界必须可由输入和结果直接验证。checkpoint commit、宿主 finalization 的固定顺序和 GitHub PR 的 open/closed/merged 模型不在本任务中重新定义。

相关文件

• lib/platform/pull-requests.ts:655-976 - create/reuse、显式 bind、external resolve 的统一 fact 写入与 typed result 边界。
• lib/internal/platform-pr.ts:16-133 - PR create、bind、resolve-external、inspect 和同步命令的 CLI 边界。
• lib/task/create.ts:185-224、.agents/templates/task.md:1-20、templates/.agents/templates/task.{en,zh-CN}.md:1-20 - 任务元数据初始化和双语模板。
• lib/task/verification-engine.ts:490-545,1096-1155、lib/platform/verification-required.ts:35-108 - required-PR、required-checks 和 post-review PR 等价性门禁。
• lib/platform/{pr-summary,pr-checks,verification-sync}.ts - PR identity 的摘要、checks 和同步消费面。
• lib/pr-review/evidence-grading.ts:62-99、lib/task/human-override.ts:607-720 - PR 反查、证据分级和人工探针。
• .agents/workflows/{feature-development,bug-fix,refactoring}.yaml:4-6 - workflow pr_tasks 对 PR 路径的策略说明。
• .agents/skills/{complete-task,create-pr,watch-pr,commit}/**、.agents/skills/complete-manual-validation/**、.agents/skills/review-{code,pr}/reference/**、.agents/rules/{task-management,compatibility-policy}.md - 用户可见的状态、身份和下一步契约。
• tests/unit/**、tests/integration/cli/**、tests/e2e/core/** - PR fact、策略门禁、同步、模板和存量 fixture 的行为覆盖。

PR fact 消费面矩阵

类别	当前入口	当前事实使用	方案阶段必须确认的切换边界
Writer	lib/task/create.ts:185-224、三份 task 模板	初始化 pr_status: pending	replace：新任务只产生规范 fact 的初始形态，不再把旧状态作为并行事实源。
Writer	lib/platform/pull-requests.ts:655-976	create/reuse、bind、external bind 写 pr_number 与 pr_status: created	replace：三类动作共用原子 fact writer；创建来源只来自实际动作结果，远端失败、竞态和重放保持 fail-closed/no-op。
CLI boundary	lib/internal/platform-pr.ts:16-133	暴露 typed PR 操作结果	replace：typed result 同时表达 identity、binding verification 和 create provenance，下游不解析 Activity Log。
Core reader	lib/task/verification-engine.ts:490-545,1096-1155	required-PR、terminal verification、post-review 按旧字段/PR 号判断	replace：统一从 fact/accessor 读取；旧 shim 单独存在不能放行。
Core reader	lib/platform/verification-required.ts:35-108	按 prFlow、旧状态和 PR 号决定 required checks	replace：分离策略、绑定、验证和远端 checks 四种语义。
Platform reader	lib/platform/pr-summary.ts:67-136、pr-checks.ts:120-130、verification-sync.ts:154-159,323-345	按 pr_number 定位远端资源	retain-with-rationale：identity 仍可能是 fact 的组成部分，但必须经规范 accessor，并在缺失/不完整时保留当前分层错误。
Review/override reader	lib/pr-review/evidence-grading.ts:62-99、lib/task/human-override.ts:607-720	反查任务和人工探针读取 PR 号	replace：通过 identity resolver 消费 fact；人工覆盖不能从旧字段补造验证或创建来源。
Workflow contract	.agents/workflows/{feature-development,bug-fix,refactoring}.yaml:4-6	缺省 pr_tasks 是否由 pr_status=skipped 排除	replace：改为规范 fact/策略契约，三种 workflow 保持一致，删除只认旧状态的进度解释。
Skill/rule contract	.agents/skills/complete-task/SKILL.md:67-101,167、reference/external-delivery.md:11-17	外部授权、complete gate 和 --force/skip 规则	replace：以 typed authorization/fact 和独立策略判断为准；current-only，不延长 shim。
Skill/rule contract	.agents/skills/create-pr/SKILL.md:32-36,67-99、.agents/skills/watch-pr/SKILL.md:40-47,73-81	创建/恢复、监控和 PR identity 绑定	replace：调用规范 writer/accessor；保留显式 PR 参数的一致性校验，删除“保持 created”语义。
Skill/rule contract	.agents/skills/complete-manual-validation/SKILL.md:60、reference/summary-update.md:3	从 task.md 读取或校验 pr_number	replace：统一从 fact accessor 取得 identity；显式 PR 参数仍须与已验证 identity 一致。
Skill/rule contract	.agents/skills/commit/reference/pr-summary-sync.md:3-7	有效 pr_number 才同步既有 PR 摘要，结果固定 no_op	retain-with-rationale：保留“commit 不创建/复用 PR、同步失败为 warning”的行为，但 identity guard 改读 fact。
Skill/rule contract	.agents/skills/review-code/reference/output-templates.md:25-29、.agents/skills/review-pr/reference/evidence-grading.md:18-36	review 出口和宿主证据分级直接读取/规定 pr_number	replace：统一 resolver；保留 PR head、Issue、freshness 和 ambiguity 的证据规则。
Rule contract	.agents/rules/task-management.md:52	规定 create-pr 更新 pr_number	replace：改为 create-pr 通过核心事件更新规范 fact，同时保留时间/版本字段更新。
Test contract/fixture	tests/unit/core/**、tests/integration/cli/**、tests/e2e/core/**、模板测试	固化旧字段、create/bind/external、策略和同步行为	replace：以规范 fact 与策略行为构造 fixture；只做正向行为和不变性断言，不以旧字符串消失作为唯一断言。

lib/task/commit-operation.ts:286-475 负责 checkpoint commit、推送和 task metadata 同步，lib/task/finalization.ts:592-729 负责 preflight → lifecycle → task comment → terminal verification 的顺序；二者是流程边界，不应重新引入 commit/finalization 双轨。方案阶段仍须对全仓 pr_number|pr_status 命中逐项分类，未分类命中不得进入实现。

可执行验收矩阵

ID	可观察输入	动作	预期结果（含反向分支）	验证层级
AC-1	新建 PR、精确复用已有 PR、显式绑定已有 PR、Issue 唯一/显式选择外部已合并 PR	通过 typed PR intent 执行并读取 fact、typed result 与远端快照	四类场景产生同一规范 fact；identity 与远端一致；binding verification 只在精确验证后成立；created-by-current-operation 仅实际 POST 为真。缺字段、竞态、身份冲突或多候选 fail closed；相同证据重放 no-op。	pull-requests 单元 + platform-pr 集成，fake API client
AC-2	旧 shim、畸形/不匹配 fact、完整且远端有效 fact	执行 complete-task preflight、required-PR gate、terminal verification	旧 shim 不能单独授权；无效/不匹配 fail 或 blocked；只有 fact 与远端验证均满足才按策略通过；post-review 仍使用真实远端证据。	verification-engine/verification-required 单元/e2e + complete-task 集成
AC-3	全仓 writer、reader、workflow/skill/rule contract、template、fixture/test 清单	静态消费矩阵审查并运行完整测试	每个命中都标记 replace、retain-with-rationale 或 delete；不存在生产路径对旧 pr_status: created 的 canonical 解释或新旧双写；保留 identity 的理由可追溯。	rg/代码审查 + unit/integration/e2e/template
AC-4	可唯一验证、只有粗粒度旧字段、旧字段与审计/远端冲突或多候选的存量记录	通过明确迁移/重新绑定入口，或运行完成/绑定验证	唯一记录转换并保存证据；歧义记录保留数据、停止写入并给出修复指引；不得从自然语言日志推断创建来源或静默标记交付。	migration/bind fixture、错误路径和状态不变性测试
AC-5	complete-task 的 --force 与 prFlow 缺省/required/disabled 组合，另含 --skip-pr	分别执行 complete-task preflight/terminal gate	disabled：PR 维度满足，--force 不创建/伪造 PR fact，其他 failed/blocked hard gate 仍停止；required + pending/skipped/无效 fact：即使 --force 也停止，只有已验证 fact 可继续，force 不能解除 required-PR；缺省 + pending：无 force/skip 时停止，--force 可越过该默认 PR 前置条件但不写成已绑定/已验证 PR，仍受其他 hard gate；--skip-pr 只在非 required 时形成明确 no-PR 结果，required 时拒绝。	complete-task、verification-engine 单元/集成
AC-5-taskless	无显式 task scope 且上下文解析返回 TASK_CONTEXT_NOT_FOUND；显式 scope 解析失败、detached head、损坏候选或多匹配	执行 direct commit，再检查 task/PR 副作用	只有无显式 scope + TASK_CONTEXT_NOT_FOUND 进入 taskless direct；成功不读写 task、review、receipt、checkpoint、Activity Log，也不做任务平台/PR fact 同步。显式 scope 失败或异常候选必须 fail closed，不能降级为 taskless；未有同等契约证据的其他 PR 操作不自动获得 taskless 语义。	commit-operation 单元 + task-context 集成
AC-5-boundary	taskless direct 与 task-bound commit 的 PR 摘要场景	比较两条 commit 路径的 fact accessor 和同步调用	task-bound 只在规范 fact 有 identity 时同步既有 PR 摘要并固定 no_op；taskless 跳过任务校验/平台同步；外围同步失败只产生 warning，不回滚主动作。	commit 集成 + warning/replay 测试

影响评估

直接影响：

• task frontmatter schema、任务创建 writer、三份发布模板和工作流进度规则。
• platform-pr create/reuse/bind/resolve-external 的持久化写回、typed result、重放和竞态行为。
• required-PR、required-checks、post-review PR 等价性、complete-task、create-pr、watch-pr、commit、review 和人工验证流程。
• PR 摘要、checks、平台同步、PR 审查证据、人工覆盖及其测试 fixture。

间接影响：

• task-finalization 生命周期顺序和 Issue/task 评论的 warning/pending 投影。
• 远端 GitHub Issue closing PR 查询、fork/base/head/SHA 身份证据和 required checks API。
• active/completed 存量任务的解释与恢复指引；无法唯一解释时必须保留数据并停止写入。

技术风险

• schema 与存量风险：旧字段无法证明创建来源或 binding 验证时，必须 current-only、fail closed；一次性转换只能位于明确边界。
• 远端副作用风险：PR 创建成功后任务写回或评论失败时，必须保留主动作事实并通过 identity 恢复，外围失败才可降为 warning。
• 身份与授权风险：fork、多个 closing PR、base/head/ref/SHA 或 merge 证据不完整时不得自动授权。
• 策略回归风险：PR 必需、任务绑定、验证通过、创建来源和 no-PR 选择必须独立，尤其不能让 --force 绕过 required-PR 或身份硬门禁。
• 消费面遗漏风险：验证、同步、审查、人工验证、workflow、rule 和技能文档分散读取字段；任何未分类命中都会造成事实漂移。
• 文档/测试漂移风险：双语模板、状态契约和 fixture 若仍暗示旧字段为真相源，会使实现看似通过但下游仍分叉。

依赖关系

• parseTaskFrontmatter/writeTask 的结构化解析和原子写回能力。
• platform-pr 平台 adapter、GitHub API、任务执行锁和远端 Git SHA 复核。
• verification-engine、required checks adapter、task-finalization 的 preflight/terminal 调用顺序。
• .agents/.airc.json 的 prFlow 策略、任务分支 delivery target 和远端 Issue/PR/checks 数据。
• create-pr、complete-task、watch-pr、commit、review、complete-manual-validation 的英中文档和测试契约。

假设

• 当前 HEAD 是 refactor: 简化 commit、create-pr 与 complete-task 流程 #906 生命周期简化和 checkpoint/delivery 改动后的实现基线；本任务不恢复已删除的 commit intent/finalization 双轨。
• pr_number 可能作为规范 fact 的 identity 组成继续保留，但最终存储形态、字段命名和 accessor 属于方案阶段决策。
• 当前代码证据只确认 direct commit 具有 taskless fallback；其他 PR 操作必须继续以各自任务上下文契约为准，不因本轮新增矩阵而扩大 taskless 范围。
• Issue refactor: 统一 PR 创建与外部绑定事实 #929 与 task.md 的目标、约束和验收标准一致。

未决问题

• 技术方案需要确定规范 fact 的最终 schema、必填证据、访问边界及 typed result 的精确对应关系。
• 技术方案需要确定旧 active/completed 任务的显式迁移/重新绑定入口与唯一验证边界；Activity Log 自然语言不能作为创建来源证据。
• 方案需要把 prFlow、--force、--skip-pr、规范 fact 和 no-PR 结果映射为可执行状态机，并明确 complete-task 的其他 hard gate 与 warning/pending 投影。
• 方案需要按 AC-3 的全仓命中清单完成最后一次 replace/retain-with-rationale/delete 分类，特别核对本轮新增的六个 skill/rule 契约。

工作量和复杂度评估

• 复杂度：高
• 风险等级：高

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

需求分析审查（Round 3）

codex · TASK-20260830-090109

需求分析审查报告

• 审查轮次：第 3 轮
• 产物文件：review-analysis-r3.md
• 审查输入：
  • analysis-r3.md

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f	14760	analysis-r2.md
f	16627	analysis-r3.md
f	9976	analysis.md
f	17131	review-analysis-r2.md
f	18103	review-analysis.md
f	8156	task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

## 产物生命周期收据

| event | output | input | input_sha256 | completed_at |
| --- | --- | --- | --- | --- |
| review-analysis.completed | review-analysis.md | analysis.md | b3e7cd263688025de95739b69f554ea91d5f88705126c78a22ed8d33f74301f8 | 2026-09-01 00:23:57+08:00 |
| review-analysis.completed | review-analysis-r2.md | analysis-r2.md | 83bb4864a5836c12a99036e67fd5f78b0e51ecdc1c81ab6e9486e3ee2118fb8d | 2026-09-01 09:19:56+08:00 |

审查摘要

• 审查者：codex
• 审查时间：2026-09-01 11:17:36+08:00
• 审查范围：analysis-r3.md、task.md、Issue refactor: 统一 PR 创建与外部绑定事实 #929、AN-1/AN-2 第三轮响应，以及 force/taskless 与 PR identity 契约证据
• 总体结论：通过
• 发现（AI 可处理）：0 阻塞项，0 主要，0 次要 / 人工校验：0

检视覆盖声明

pass_id	scope	evidence	result	gaps_or_assumptions
pass-1	独立读取第三轮分析、任务来源和当前契约	analysis-r3.md:26-138、task.md:24-70、complete-task/commit 定点行	需求、验收、影响、风险和开放问题足以进入方案	历史 Issue 编号关系不影响本轮结论
pass-2	来源—验收—消费面—风险追踪	analysis-r3.md:55-87 与下方追踪矩阵	AC-1..AC-5-boundary 可验证，消费类别及最终未分类命中门禁完整	精确 schema 仍按职责留给方案阶段
pass-3	compatibility-budget 风险镜头	.agents/rules/compatibility-policy.md、analysis-r3.md:59-75,81-84,106	current-only、显式迁移/重新绑定、禁止双写和歧义失败关闭合规	未新增兼容预算，期限/退出条件不适用
pass-4	反证 AN-1/AN-2 的 accepted 响应	complete-task/SKILL.md:71-84,163-167、commit/SKILL.md:18-25,74-86、六契约路径反查	修订稿与当前契约一致；未找到足以维持 finding 的反证	commit/reference/task-status-update.md 由 related-files 的 commit/** 与 AC-3 未分类命中门禁承接，方案仍须逐项分类
pass-5	finding、人工校验、裁决与 verdict 收敛	AN-1/AN-2 复核块、账本第 3 轮 accepted 响应	两条 accepted finding 均可 closed；0 新 finding、0 人工校验、0 人工裁决	finding 已在上限轮次内收敛，无需升级人工裁决

lens_id	trigger_evidence	loaded	result
compatibility-budget	analysis-r3.md:59-75,81-84,106 涉及删除旧 schema 与 legacy 转换	yes	current-only；不保留 shim/双写，歧义保留数据并失败关闭
documentation-antipatterns	analysis 阶段不适用	not-applicable	注册表限定 code 阶段
testing-discipline	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；本轮只审查测试输入完整性
security-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；安全角色单独覆盖
migration-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；迁移由兼容镜头覆盖
concurrency-risks	analysis 阶段不适用	not-applicable	注册表限定 code 阶段；竞态/重放作为质量属性覆盖
cross-platform-risks	analysis 阶段不适用	not-applicable	来源未触发 OS 行为变化，且注册表限定 code 阶段

需求分析专项覆盖

perspective_id	applicability	reviewed_scope	evidence	result_or_gap
user	applicable	单一 fact、策略行为、恢复指引和验收	task.md:60-66、analysis-r3.md:37-41,77-87	covered
maintainer	applicable	writer/reader/contract、兼容与长期维护	analysis-r3.md:43-75,104-111	covered
operations	applicable	远端副作用、重放、warning、恢复和 taskless 副作用	analysis-r3.md:81,84-87,98-102,106-109	covered
security	applicable	identity、fork、多候选、授权和 hard gate	analysis-r3.md:81-82,85,101,108-109	covered
testing	applicable	输入、动作、预期结果、反向分支和验证层级	analysis-r3.md:77-87	covered

quality_id	source	stakeholder	priority_or_tradeoff	verification	result_or_gap
QA-identity	SRC-TASK	user, security	高；identity/verified/provenance 独立	四类 PR 路径 fact/result/远端快照对照	covered
QA-atomicity	SRC-TASK	maintainer, operations	高；主动作不被附属同步回滚	故障注入、重放 no-op 与状态不变性检查	covered
QA-compat-current-only	SRC-TASK	maintainer	高；禁止双写和日志猜测	legacy 唯一/歧义 fixture 与显式恢复	covered
QA-policy-preservation	SRC-TASK	user, testing	高；force/skip/taskless/prFlow 不漂移	AC-5、AC-5-taskless、AC-5-boundary	covered
QA-scope-completeness	SRC-TASK	maintainer	高；所有 consumer 同变更处理	消费矩阵 + 全仓未分类命中门禁	covered

evolution_id	source	confirmation_status	classification	boundary_evidence	result_or_gap
EV-legacy-task	SRC-TASK	confirmed	design-input	task.md:51-52,65、analysis-r3.md:84,102,106	covered
EV-schema-shape	SRC-ANALYSIS-R3	unconfirmed	open-question	analysis-r3.md:124,130 明确留给方案且不预设字段形态	covered

acceptance_id	observable_input	action	expected_result	status_or_gap
AC-1	create/reuse/bind/external	typed intent + fact/result/远端快照	同一 fact、三语义独立、错误 fail closed、重放 no-op	verifiable
AC-2	old shim、无效 fact、有效 fact	preflight/required-PR/terminal	旧 shim 不授权；无效停止；有效按远端与策略通过	verifiable
AC-3	全仓 consumer 与契约	逐项分类 + 完整测试	每个命中 replace/retain/delete，无旧 canonical 解释或双写	verifiable
AC-4	唯一、粗粒度、冲突 legacy 记录	显式迁移/重新绑定/验证	唯一转换；歧义保留数据、停止写入并给指引	verifiable
AC-5	force × prFlow + skip	complete preflight/terminal	force 不绕 required/identity hard gate；缺省行为与 skip 语义明确	verifiable
AC-5-taskless	无 scope/not-found 与异常上下文	direct commit + 副作用检查	仅合法 not-found 降级；异常 fail closed；成功无任务/PR 副作用	verifiable
AC-5-boundary	taskless/task-bound commit	比较 fact accessor 与同步	bound 有 identity 才摘要；taskless 跳过；外围失败不回滚	verifiable

追踪矩阵

source_id	upstream	reviewed_target	verification	status_or_gap
SRC-TASK	task.md:24-70 目标、约束、验收	analysis-r3.md:37-133	AC-1..AC-5-boundary、影响、风险、未决问题逐项对照	covered
SRC-ISSUE	GitHub Issue #929	analysis-r3.md:26-30,126	platform-issue inspect	covered；Issue 未增加额外验收
SRC-AN-1	review-analysis-r2.md#AN-1	analysis-r3.md:34,41,67,77-87,109,125,132	complete-task/commit 原文反证	covered；accepted 响应关闭
SRC-AN-2	review-analysis-r2.md#AN-2	analysis-r3.md:35,52,55-75,83,110,119,133	六路径存在性和分类核对	covered；accepted 响应关闭
SRC-COMPAT	old created shim 与 legacy records	analysis-r3.md:59-75,81-84,106,124	compatibility policy	covered；无长期兼容预算

上一轮 finding 复核

AN-1：验收矩阵策略分支已补齐

• 执行方状态：accepted（Round 3）
• 复核结论：closed（执行方已按 finding 修复）。
• 证据：analysis-r3.md:85-87 明确 force×prFlow、skip、taskless direct commit 和 task-bound boundary；与 .agents/skills/complete-task/SKILL.md:71-84,163-167、.agents/skills/commit/SKILL.md:18-25,74-86 一致。
• 反证结果：未发现 force 绕过 required/identity hard gate，或 taskless 能力扩张到无契约 PR 操作。

AN-2：遗漏 identity 契约已纳入消费矩阵

• 执行方状态：accepted（Round 3）
• 复核结论：closed（执行方已按 finding 修复）。
• 证据：analysis-r3.md:69-72 逐项覆盖 complete-manual-validation、commit PR summary、review-code、review-pr 与 task-management；analysis-r3.md:83 要求全仓每个命中分类并阻止未分类命中进入实现。
• 反证结果：上一轮六个缺失路径均能在修订稿定位；保留 identity 的路径附有 rationale。

问题清单

阻塞项（必须修复）

（无）

主要问题（建议修复）

（无）

次要问题（低影响但需闭环）

（无）

非阻塞建议

（无）

人工校验项

（无）

审查分歧账本回写

• AN-1：finding-review --status closed --evidence review-analysis-r3.md#AN-1。
• AN-2：finding-review --status closed --evidence review-analysis-r3.md#AN-2。
• 本轮无新 finding，无 needs-human-decision。

证据原文

• 断言：第三轮验收矩阵完整覆盖 force、skip 和有证据的 taskless commit 边界。

$ awk -F'|' '/^\| AC-(1|2|3|4|5|5-taskless|5-boundary) / {gsub(/^ +| +$/, "", $2); print NR ":" $2}' .agents/workspace/active/TASK-20260830-090109/analysis-r3.md
81:AC-1
82:AC-2
83:AC-3
84:AC-4
85:AC-5
86:AC-5-taskless
87:AC-5-boundary

• 断言：上一轮六个遗漏契约均已在第三轮分析中定位并分类。

$ rg -n "complete-manual-validation/(SKILL|reference/summary-update)|commit/reference/pr-summary-sync|review-code/reference/output-templates|review-pr/reference/evidence-grading|rules/task-management" .agents/workspace/active/TASK-20260830-090109/analysis-r3.md
35:- **AN-2 / finding-2：accepted**。已核实 `review-analysis-r2.md#AN-2` 的六个遗漏路径及其 `pr_number` 命中：`complete-manual-validation` 主文档与摘要更新 reference、commit PR summary reference、review-code 出口、review-pr 证据分级 reference、`.agents/rules/task-management.md`。本轮在消费面矩阵中逐项补入，并为每项标明 `replace` 或 `retain-with-rationale`；同时保留全仓语义检索作为方案阶段的未分类命中门禁。
69:| Skill/rule contract | `.agents/skills/complete-manual-validation/SKILL.md:60`、`reference/summary-update.md:3` | 从 task.md 读取或校验 `pr_number` | `replace`：统一从 fact accessor 取得 identity；显式 PR 参数仍须与已验证 identity 一致。 |
70:| Skill/rule contract | `.agents/skills/commit/reference/pr-summary-sync.md:3-7` | 有效 `pr_number` 才同步既有 PR 摘要，结果固定 `no_op` | `retain-with-rationale`：保留“commit 不创建/复用 PR、同步失败为 warning”的行为，但 identity guard 改读 fact。 |
71:| Skill/rule contract | `.agents/skills/review-code/reference/output-templates.md:25-29`、`.agents/skills/review-pr/reference/evidence-grading.md:18-36` | review 出口和宿主证据分级直接读取/规定 `pr_number` | `replace`：统一 resolver；保留 PR head、Issue、freshness 和 ambiguity 的证据规则。 |
72:| Rule contract | `.agents/rules/task-management.md:52` | 规定 create-pr 更新 `pr_number` | `replace`：改为 create-pr 通过核心事件更新规范 fact，同时保留时间/版本字段更新。 |

• 断言：账本中的 AN-1/AN-2 均为第三轮 accepted，具备相称修订证据。

$ nl -ba .agents/workspace/active/TASK-20260830-090109/task.md | sed -n '122,126p'
122 | id | stage | round | severity | status | evidence |
123 |----|-------|-------|----------|--------|----------|
124 | AN-1 | analysis | 3 | major | accepted | 已核实...AC-5、AC-5-taskless、AC-5-boundary... |
125 | AN-2 | analysis | 3 | major | accepted | 已核实...六个遗漏契约...replace 或 retain-with-rationale... |

• 断言：Issue refactor: 统一 PR 创建与外部绑定事实 #929 仍与任务绑定且未提供额外验收。

$ agent-infra-internal platform-issue inspect TASK-20260830-090109 | node -e '<select issue fields>'
{"status":"no-op","issue":{"number":929,"state":"open","title":"refactor: 统一 PR 创建与外部绑定事实"},"task":{"id":"TASK-20260830-090109","issueNumber":929}}

自我质疑

• 未直接核验 refactor: 简化 commit、create-pr 与 complete-task 流程 #906/refactor(lifecycle): 简化交付生命周期流程 #908/refactor(cli): 重构提交检视与目标分支闭环  #940 的历史提交关系；分析已把当前 HEAD 作为基线，且通过明确流程边界约束避免依赖编号结论。
• analysis-r3.md 对部分目录使用 glob 归类而非逐文件列举；AC-3 明确要求方案阶段对全仓每个命中完成 replace/retain/delete 分类，未分类不得实现，因此分析阶段已提供可验证的范围闭环。

亮点

• 第三轮把 force、skip、taskless 和 task-bound summary 的差异落成可观察正反分支，没有扩大现有 taskless 契约。
• 消费面覆盖 runtime、workflow、skill、rule、template 和 tests，并为保留 identity 的读取给出理由。
• current-only、显式恢复、远端身份验证和外围 warning 的边界清晰，可直接作为方案输入。

与方案一致性

• 实现与技术方案一致（尚未进入方案/实现阶段）
• 没有意外的范围扩张

结论与建议

审查决定

• 通过
• 需要修改
• 拒绝

下一步

进入技术方案设计，依据消费面矩阵和 AC-1..AC-5-boundary 确定规范 fact schema、accessor、原子迁移边界与测试策略。

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109

[CodeCasterX]

技术方案（Round 1）

codex · TASK-20260830-090109

技术方案

• 方案轮次：Round 1
• 产物文件：plan.md
• 方案状态：待人工审查；HD-1 是进入实现前必须确认的持久化 schema 决策。

状态核对

$ git status -s
(empty)
$ ls -la .agents/workspace/active/TASK-20260830-090109/
f 14760 analysis-r2.md
f 16627 analysis-r3.md
f 9976 analysis.md
f 17131 review-analysis-r2.md
f 14298 review-analysis-r3.md
f 18103 review-analysis.md
f 7993 task.md
$ tail .agents/workspace/active/TASK-20260830-090109/task.md

产物生命周期收据

event	output	input	input_sha256	completed_at
review-analysis.completed	review-analysis.md	analysis.md	b3e7cd263688025de95739b69f554ea91d5f88705126c78a22ed8d33f74301f8	2026-09-01 00:23:57+08:00
review-analysis.completed	review-analysis-r2.md	analysis-r2.md	83bb4864a5836c12a99036e67fd5f78b0e51ecdc1c81ab6e9486e3ee2118fb8d	2026-09-01 09:19:56+08:00
review-analysis.completed	review-analysis-r3.md	analysis-r3.md	8d89a51e1f21a44867ac526e4add87bcee318ffc9e27b17fb700514795ef5b08	2026-09-01 11:22:59+08:00

方案输入与目标

输入为 analysis-r3.md，需求分析已覆盖 PR fact 的 writer、runtime reader、workflow/skill/rule contract、模板、fixture/test，以及 prFlow、--force、--skip-pr 和 taskless direct commit 分支。分析阶段的两轮审查 finding 已闭环，stage-status --stage analysis 返回 canAdvance=true。

本方案只解决持久化事实和消费边界，不恢复已删除的 commit intent/finalization 双轨，不改变 GitHub PR 的 open/closed/merged 模型，也不为旧字段增加长期兼容层。

问题理解

任务需要把 PR identity、binding verification 和 creation provenance 收敛为一个可验证的持久化事实，并让创建、复用、显式绑定、外部发现、完成校验、同步和审查流程共同消费它。当前 pr_number 与 pr_status 同时承载多种语义，且读写点分散；本方案的成功标准是一次原子写入、一个 accessor、无旧新双写，并保持既有策略和失败语义。

约束条件

• 不恢复已删除的 commit intent/finalization 双轨，不改变 GitHub PR 的 open/closed/merged 模型。
• 不增加长期兼容预算；旧字段只可在单一显式迁移边界读取，无法唯一解释时保留数据并 fail closed。
• PR identity、binding verification、created provenance、prFlow 策略和 no-PR 决定必须独立可判定。
• PR 创建后的任务写回、评论或摘要同步失败不得删除已成功主动作；外围失败按 warning 处理。
• taskless 语义只适用于已证实的 direct commit fallback，不扩张到其他 PR 操作。

方案概述

建立一个由任务元数据承载、由唯一 accessor 读取、由统一 mutation 写入的 pr_delivery_fact。它是 PR 交付和绑定语义的唯一持久化事实，采用版本化的判别联合：

• unbound：任务尚未绑定 PR；新任务的初始状态。
• skipped：用户在非 required PR 策略下显式选择无 PR；这是明确的 no-PR 决定，不等同于 PR 已创建。
• bound：包含完整远端 identity、已验证的 binding 证据和创建来源。

建议的规范数据模型如下，字段名在 HD-1 裁决后固定；示例表示运行时对象，持久化时编码为单个无换行 JSON scalar：

type PrDeliveryFact =
  | { version: 1; state: 'unbound'; reason: 'initial' | 'migrated' }
  | { version: 1; state: 'skipped'; reason: 'explicit'; decidedAt: string }
  | {
      version: 1;
      state: 'bound';
      identity: {
        repository: string;
        number: number;
        nodeId: string;
        url: string;
        head: { repository: string; ref: string; sha: string };
        base: { repository: string; ref: string; sha: string };
      };
      binding: {
        status: 'verified';
        source: 'created' | 'reused' | 'explicit-bind' | 'external-unique' | 'external-explicit' | 'legacy-migrated';
        verifiedAt: string;
        issueNumber: number | null;
        remoteState: 'open' | 'closed';
        mergedAt: string | null;
        mergeCommitSha: string | null;
      };
      provenance: { createdByOperation: boolean };
    };

identity 保存远端资源定位和 base/head/SHA 证据；binding.status 只在完整远端核验成功后为 verified；provenance.createdByOperation 只由实际 POST 创建结果写为 true，复用、显式绑定、外部发现和存量迁移均为 false。一次重放不会用本次 no_op 覆盖原始 provenance。CLI typed result 继续以 pr_created、pr_reused、no_op 区分当前调用结果，下游不得从 Activity Log 推断来源。

技术方法

1. 建立 fact domain module 和唯一读写边界

新增 lib/task/pr-delivery-fact.ts，集中定义：

• PrDeliveryFact、PrIdentity、binding evidence 和 source 类型。
• encodePrDeliveryFact：以稳定 key 顺序生成紧凑 JSON，保证相同 fact 的重放可比较。
• readPrDeliveryFact：使用严格的 typed frontmatter 解析和 schema 校验；缺失、JSON 损坏、版本未知、identity 不完整或 binding 非 verified 返回稳定错误，不回退到旧字段。
• prDeliveryFactMutation：返回可组合到 writeTask 的 frontmatter mutation。
• boundPrIdentity、hasVerifiedPrDelivery 等窄 accessor，禁止调用方直接解析 JSON 或 frontmatter。

必要时从 lib/task/write.ts 导出现有 TaskMutation/frontmatter mutation 类型，使 fact mutation 能与 assigned agent、Activity Log 一起通过一次原子 writeTask 写入。不要新增第二个文件格式或单独的事实缓存。

2. 统一 PR 获得路径的写回和结果语义

修改 lib/platform/pull-requests.ts：

• resolvedContext 通过 fact accessor 取得 bound identity；issue_number 仍是 Issue 元数据，不能被 PR fact 替代。
• bindIdentity 接收明确的 source、远端快照和创建 provenance，在同一个 writeTask mutation 中写 fact、assigned agent 和准确的 Activity Log。显式 bind 日志不再冒充 Create PR。
• 新建流程只有实际成功的 PR POST 才写 source=created 与 createdByOperation=true；远端 branch/identity 校验失败不写 fact。
• 精确复用已有 PR 写 source=reused 与 createdByOperation=false；同一完整 fact 的再次执行返回 no_op，保留原 provenance。
• 显式 bind 写 source=explicit-bind；绑定前和写回前都重新抓取并验证 repository、number、base/ref、head/ref/SHA，冲突或竞态 fail closed。
• external resolve 写 source=external-unique 或 external-explicit；只有 Issue closing PR 的权威候选经过 repository、merged、identity 完整性和唯一性校验后才写入。多候选、身份冲突和证据缺失不改变任务。
• inspect、sync、summary-sync 使用 accessor 提供 identity；不会再从 pr_status 或 Activity Log 补语义。

保留当前的锁、远端 branch SHA 复核、POST 后恢复和外围 warning 语义；fact 写回失败时不删除远端 PR 或 branch，下一次通过完整 identity 恢复。

3. 设置明确的存量迁移边界

新增 platform-pr migrate-fact 作为一次性显式转换入口，由 lib/internal/platform-pr.ts 暴露并由 platform 层实现。它是唯一允许读取旧 pr_number/pr_status 的边界，读取后立即转成当前 fact 或失败关闭；业务 reader 不感知旧格式。

迁移规则：

1. 旧任务带有效 PR 号：调用远端 inspect，确认任务仓库、PR identity、base/head/SHA 和必要的 merge 证据一致后，写 bound、source=legacy-migrated、createdByOperation=false，并在同一原子写入中移除旧字段。
2. 旧任务无可验证 PR：必须显式传入 no-PR 决定（例如 --state unbound 或 --state skipped，命令接口按裁决后的 schema 命名），才能写当前 fact；不得仅凭旧日志或隐含默认值猜测。
3. 旧字段与远端冲突、PR 不存在、身份不完整或存在多候选：不写入、不删除旧数据，返回稳定修复提示，要求显式重新绑定或人工处理。
4. 迁移成功后所有正常路径只读取 pr_delivery_fact；不保留旧新双写、不在主流程回退旧字段，也不为迁移逻辑设置无期限 shim。

4. 切换所有 runtime readers 和策略 gate

• lib/task/verification-engine.ts：required-PR、terminal verification、post-review PR equivalence 读取 bound fact 的 identity/verified 状态。旧 pr_status: created 单独存在不能放行。
• lib/platform/verification-required.ts：先判 prFlow，再判 fact state。disabled 跳过 PR checks；required 只有 verified bound fact 才满足；default 下 skipped 代表显式 no-PR，unbound 继续受 pending/force 规则控制。远端 checks 仍独立验证。
• lib/platform/pr-summary.ts、lib/platform/pr-checks.ts、lib/platform/verification-sync.ts：只从 accessor 取得 PR number/identity；没有 bound fact 时保持当前 skip/failure 层级，但错误消息改为当前 fact 语义。
• lib/pr-review/evidence-grading.ts、lib/task/human-override.ts：使用 identity resolver；显式 PR 参数仍需与绑定 identity 一致，不能用旧字段补造授权。
• lib/task/commit-operation.ts、lib/task/finalization.ts：保持现有职责和顺序，仅消费被替换后的 summary/verification 边界，不重新增加 PR 状态写入或第二条生命周期。

5. 更新工作流、技能、规则、模板和测试契约

• 三份 workflow 的 pr_tasks 说明改为基于 prFlow 和 fact state 的策略，而不是 pr_status=skipped。
• complete-task、create-pr、watch-pr、complete-manual-validation、commit、review-code、review-pr 的主文档和 references 改用 fact/accessor 术语；保留必要的 identity 一致性检查、--force hard gate、taskless commit 和同步 warning 行为。
• 三份 task 模板和 lib/task/create.ts 初始化 pr_delivery_fact，移除 pr_status 的新任务写入和文档契约。
• 所有测试 fixture 通过 fact helper 构造；不增加“旧字符串必须不存在”的脆弱反向断言，而是验证当前 fact 行为和旧输入的 fail-closed/显式迁移行为。

方案对比

方案 A：单一 JSON fact + 唯一 accessor（推荐）

把完整判别联合编码到一个 pr_delivery_fact frontmatter scalar，所有 writer/reader 通过 domain module 操作。

• 优点：持久化只有一个事实键，identity、验证状态和 provenance 原子一致；新增字段不会出现半套 fact；可以用 schema version 明确拒绝未知格式。
• 代价：task.md 中的 fact 对人不如多个字段直观；需要严格 JSON 编解码、大小限制和 typed accessor 测试。
• 适用性：现有 frontmatter 已限制为 scalar，单 scalar 是在不引入第二文件的前提下表达结构化数据的最小方式。

方案 B：多个扁平 fact 字段

用 pr_identity_*、pr_binding_*、pr_created_by_operation 等多个 scalar 保存同一 fact。

• 优点：人类直接阅读 task.md 较方便，局部字段可以被简单工具读取。
• 代价：字段数量多，任何 writer 遗漏一个字段都会产生不完整事实；所有 readers 仍需一个组合 accessor；schema 演进和原子一致性测试更复杂。
• 例子：像把一张身份证拆成多张便签，便签都在但缺一张时很难判断整组资料是否可信。

方案 C：独立 delivery 文件

将 fact 存入任务目录下单独的 JSON 文件，task.md 只保留引用。

• 优点：JSON schema 原生，结构表达和版本迁移较容易。
• 代价：task.md 与 delivery 文件形成两个需要原子协调的持久化对象；平台评论、任务迁移和目录生命周期都要额外处理；会引入本任务明确不需要的第二事实文件。
• 例子：把订单状态放到另一个抽屉，订单本身搬家或评论同步时必须同时搬两个抽屉，容易出现一边更新、一边没更新。

实施步骤

1. 实现 fact domain module：新增类型、编码/解码/schema 校验、窄 accessor 和 mutation；导出必要的 TaskMutation 类型。
   • verify：新增单元测试覆盖三种 state、完整/不完整 identity、未知版本、稳定序列化、无效 JSON 和 mutation 原子组合。
2. 替换 PR writer 和 CLI typed result：改造 create/reuse、bind、external resolve、inspect 和 sync，集中使用 fact writer/accessor，保留锁和远端复核。
   • verify：pull-requests 单元和 platform-pr 集成覆盖四条 PR 获得路径、实际 POST provenance、重放 no-op、竞态、冲突、外部多候选和同步 warning。
3. 实现显式存量迁移入口：添加 migrate-fact CLI 和 platform core；只在该边界读取旧字段，成功原子移除旧字段，失败保持原文档不变。
   • verify：唯一可验证旧 PR、旧无 PR 显式决定、身份冲突、多候选、远端缺失和重复运行 fixture；确认普通 reader 不再读取旧字段。
4. 替换验证、同步、审查和人工覆盖 readers：切换 verification-engine、required checks、summary/checks/sync、evidence grading 和 human override。
   • verify：required/default/disabled、bound/skipped/unbound、远端身份不匹配、旧 shim-only、--force、--skip-pr 的正反行为测试；post-review 仍使用真实远端证据。
5. 同步 workflow、skills、rules、模板和 fixtures：按分析矩阵逐项执行 replace、retain-with-rationale 或 delete，双语文件保持一致。
   • verify：全仓 rg 对 pr_number|pr_status 的每个命中都能在方案清单中分类；运行模板、契约、unit、integration 和 e2e 测试，不使用关键词删除断言替代行为测试。
6. 执行整体验证和人工检查准备：运行构建、完整测试，检查 taskless commit 不产生任务副作用，检查平台 warning 不回滚主动作，并记录与方案偏差。
   • verify：npm run build、npm test 通过；人工审查确认 HD-1 已裁决、无未分类 writer/reader、无新旧双写，再允许进入 code-task。

文件清单

新建文件

• lib/task/pr-delivery-fact.ts：规范 fact 类型、schema 校验、编码、读取和 mutation。
• lib/platform/pr-delivery-migration.ts：一次性显式旧任务转换边界（如实现阶段证明放入 pull-requests.ts 更符合现有结构，可合并到该文件，但不得把迁移逻辑散落到 readers）。
• tests/unit/task/pr-delivery-fact.test.ts：fact codec/schema/accessor 的单元测试。

修改文件

• lib/task/write.ts、lib/task/create.ts：支持 fact mutation，初始化规范 fact，停止新写入旧字段。
• lib/platform/pull-requests.ts、lib/internal/platform-pr.ts：统一 create/reuse/bind/external writer、typed result、inspect/sync 和迁移命令。
• lib/task/verification-engine.ts、lib/platform/verification-required.ts：切换 PR delivery 和 required checks gate。
• lib/platform/pr-summary.ts、lib/platform/pr-checks.ts、lib/platform/verification-sync.ts：切换 identity accessor。
• lib/pr-review/evidence-grading.ts、lib/task/human-override.ts：切换 PR identity 反查和探针。
• .agents/workflows/feature-development.yaml、bug-fix.yaml、refactoring.yaml：更新 PR 路径进度契约。
• .agents/skills/complete-task/**、create-pr/**、watch-pr/**、commit/**、complete-manual-validation/**、review-code/**、review-pr/**：更新状态、identity、迁移和下一步说明；同步英中文件。
• .agents/rules/task-management.md：更新 create-pr 的状态写入契约。
• .agents/templates/task.md、templates/.agents/templates/task.en.md、task.zh-CN.md：更新 frontmatter schema 和说明。
• tests/unit/platform/pull-requests.test.ts、tests/integration/cli/platform-pr.test.ts 及相关 verification/summary/checks/review/override 测试：改造 fixture 和行为断言。
• tests/unit/core/pr-status-contract.test.ts、requires-pr-gating.test.ts、tests/e2e/core/validate-artifact-required-checks.test.ts 等旧契约测试：改为 fact/策略行为测试；删除只服务于旧 canonical 字段的测试专属契约。

明确不修改的边界

• lib/task/commit-operation.ts 和 lib/task/finalization.ts 不新增 PR 状态机或第二事实源，只调整其下游调用的 accessor。
• GitHub PR 远端状态模型、checkpoint commit 语义和已有 warning/retry 机制不重定义。

验证策略

• 单元测试：fact codec/schema/accessor、三种 state、稳定序列化、完整/不完整 identity、未知版本和 mutation 原子性。
• 平台集成测试：create/reuse/bind/external 四条路径、实际 POST provenance、重放 no-op、远端竞态、身份冲突、外部多候选和同步 warning。
• 门禁测试：required/default/disabled、bound/skipped/unbound、--force、--skip-pr、旧 shim-only、远端不匹配和 taskless commit 的正反结果。
• 迁移测试：唯一可验证旧 PR、显式 no-PR、旧字段冲突/缺失/多候选、失败时 task.md 不变和成功后旧字段移除。
• 契约与模板测试：三份 workflow、双语 skill/rule/template 与 fixture 同步；全仓 pr_number|pr_status 命中都有 replace/retain/delete 分类。
• 完整验证命令：npm run build、npm test；外部 GitHub 状态使用 fake client 或现有隔离 fixture，真实平台人工检查仅验证权限/远端恢复边界。

数据流与失败语义

PR intent
  -> remote identity/branch/Issue validation
  -> verified PrDeliveryFact
  -> one atomic task write (fact + agent + activity when applicable)
  -> typed primary result
  -> readers/accessors
  -> remote revalidation in completion/checks gates

• 任何远端 identity、授权、候选唯一性或 fact schema 失败：主操作返回 failed/blocked，不写错误 fact。
• task metadata、评论或摘要同步失败：保留已成功的主 fact/PR，按现有 warning 语义处理，不回滚主动作。
• fact 缺失或未知版本：正常 reader fail closed，并提示执行显式迁移或重新绑定；不尝试旧字段回退。
• 迁移仅在显式命令中发生，并以一次原子 task 写入提交；失败时旧文件保持不变。

兼容性、回滚与发布边界

本任务不获准增加长期兼容预算。旧字段的读取集中在 migrate-fact 单一边界，迁移成功即删除旧字段；未能唯一解释的任务保留原数据并提示重新绑定。实现中不得新增 TODO(compat) 之外的隐式兼容分支，也不得让 normal create/complete/verify 继续同时理解新旧格式。

回滚只针对尚未完成存量迁移的代码版本回退；已成功迁移的任务不应自动写回旧字段。迁移命令本身必须具备原子写回和重复执行 no-op/明确冲突行为，避免回滚或重试产生第二套事实。

假设

• task.md frontmatter 的 scalar 限制保持不变，因此 JSON scalar 方案不依赖 YAML nested object 支持。
• PlatformChangeRequestSnapshot 已提供完整 identity、base/head 和 merge 字段，fact 不重复保存 PR body、labels 等非绑定授权数据。
• 方案审查批准后，编码阶段可以对现有旧字段测试 fixture 做一次性迁移，不需要支持旧调用方继续写入旧字段。

未决问题

• HD-1 需要决定规范 fact 使用单 JSON scalar 还是多个扁平字段；该选择影响持久化 schema、模板、所有 accessor 和测试 fixture。
• 需要在方案审查中确认 migrate-fact 的 no-PR 参数名称，以及 skipped fact 是否记录操作者身份或仅记录时间；不影响 current-only 和 fail-closed 原则。
• 需要在编码前确认现有 platform CLI 对新增 migration operation 的命令注册测试位置。

人工裁决待办

HD-1：规范 PR delivery fact 的持久化形状 [needs-human-decision]

• 要决定什么：任务元数据中的规范 PR delivery/binding fact 采用“单一 JSON scalar”还是“多个扁平 frontmatter 字段”。
• 为什么现在要决定：现有 frontmatter 解析器只接受 scalar；两种形状都能实现，但会改变所有 writer、reader、模板、迁移和 fixture 的接口。没有统一选择，编码时可能出现半套字段或第二事实源。
• 会影响什么：task.md schema、lib/task/pr-delivery-fact.ts 的 accessor、PR create/bind/external 写回、verification/summary/review consumers、存量迁移方式和测试构造器。
• 如果选错或暂不处理：同一个任务可能出现 identity 已写入但 verification/provenance 缺失，或不同模块读取不同字段；方案无法形成“一次切换、唯一事实”的实现门禁。

方案 A：单一 JSON scalar（推荐）

• 实际会怎么做：增加一个 pr_delivery_fact scalar，把 state、完整 identity、verified binding evidence 和 creation provenance 作为版本化判别联合编码；所有代码只经过一个 parser/accessor 读写。
• 选了以后会怎样：一次 mutation 可以整体替换 fact；缺失字段、未知版本或损坏 JSON 在边界被拒绝；task.md 中的人类阅读需要依赖结构化命令或摘要查看细节。
• 好处：事实只有一个键，原子性和 schema 完整性最好；不会产生多个字段之间的组合歧义；版本号能明确 fail closed。
• 代价：JSON 字符串可读性较低；需要限制长度、稳定序列化和更严格的 codec 测试；局部字段查询必须通过 accessor。
• 例子/类比：像把一份完整合同装进一个有版本号的文件袋，交接时整袋替换，不会只换掉“编号”却忘记“签字页”。

方案 B：多个扁平 frontmatter 字段

• 实际会怎么做：分别增加 identity repository/number/head/base、binding status/time/source 和 provenance 等 scalar 字段，由 accessor 组合成运行时 fact；所有 writer 必须在同一次 mutation 中更新整组字段。

• 选了以后会怎样：task.md 直接显示各字段，但任何旧字段残留、字段漏写或部分更新都必须由 accessor 判定为 invalid；schema 增加字段时要同步扩展模板、writer 和校验。

• 好处：人类和简单脚本更容易读取单个 identity 字段；不需要 JSON 编解码。

• 代价：字段组容易漂移，原子写入仍不能消除旧数据半套组合；迁移、版本演进和结构性测试更大；多个空字段可能被误认为“已绑定”。

• 例子/类比：像把合同拆成很多便签，查找编号很快，但少一张签字便签时必须额外核对整套资料，维护成本更高。

• 建议选哪个：方案 A。

• 为什么这样建议：项目当前 frontmatter 已是 scalar-only，而任务核心要求单一、结构化、可验证事实。单 JSON scalar 最直接地保证 identity、binding verification 和 provenance 同步提交；可读性代价可由 CLI inspect/summary 解决，且比维护多个并行字段更易验证和回滚。

复杂度、风险与人工审查门禁

• 实施规模：高；涉及 3 个新文件、约 20 类现有代码/文档/测试入口。
• 技术风险：高；主要风险是 fact schema 漂移、存量迁移误判、远端竞态和遗漏 reader。
• 人工审查门禁：本方案产出后停止。维护者需先裁决 HD-1，再审查文件清单、迁移边界和 AC-1..AC-5 的实现覆盖；批准后才能运行 code-task。

---

由 codex 自动生成 · 内部追踪：TASK-20260830-090109