完成任务

--agent 取值见 .agents/rules/task-management.md「合作者 token 规范」。

宿主 finalization 使用 receipt v4（不可变 receiptId、单调 revision、摘要暂存和 canonical warnings）。生命周期/身份/required PR 等硬失败返回 result: failed|blocked；生命周期完成后，只重试 receipt 指出的 pending 外围步骤或 open backfill warning。逐检查 verification warning 以 observed target 为单位转换：新观察替代旧 code 时保留旧行 resolved 历史，未观察的 target 不变。

行为边界 / 关键规则

持久化报告证据

生成收尾报告或同步内容时，先读取 .agents/rules/evidence-reporting.md。成功检查记录命令、范围、状态/结构化结果、实际结果和未覆盖部分；失败、阻塞或争议保留复现入口、准确位置和决定性摘录。

• 本命令由宿主更新任务元数据并原子移动任务目录
• 入口接受可选 --external-pr <N>；仅用于外部交付候选歧义时的显式选择，不绕过身份或平台门禁

版本戳规则：创建或更新 task.md frontmatter 时，先读取 .agents/rules/version-stamp.md，并写入或刷新 agent_infra_version。

第 0 步：状态核对（执行前硬约束）

在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。

运行以下命令，并在本轮产物的 ## 状态核对 段记录任务/产物范围、关键结果和未覆盖部分；正常成功不粘贴完整目录清单或 task.md 尾部。失败、阻塞、身份不一致或争议时，附决定性原文行：

agent-infra-internal task-snapshot {task-id} --format text

状态核对完成前，禁止任何关于外部状态的断言（例如“代码没变”“测试已通过”“没有其他引用”），包括思考阶段。本门禁只提供结构下限；逐条证据配对和真实性仍需按报告模板与审查要求核对。

任务上下文解析

入口可省略 task ref；显式 task scope 仅接受 --task <ref> 或 -t <ref>，不再解释位置 task ref。保留其余业务操作数后调用 agent-infra-internal task-context resolve {task-scope}；{task-scope} 为空或 task flag 之一。只读取结构化结果的 taskId，后续把 {task-id} 绑定为完整 TASK-YYYYMMDD-HHMMSS。解析失败时透传非零退出码，不自行扫描任务。

解析任务引用，并确认任务位于本技能支持的状态或目录且存在 task.md；无法定位时按未找到任务处理并停止。

步骤开始：本地生命周期边界

正常完成路径在 active 阶段完成业务更新、平台同步和预完成门禁后，才由步骤 6 的单次 finalization intent 按固定顺序原子推进生命周期、终态 task 评论和完成校验；不得提前手工写入这些机械状态。已归档任务只允许进入 finalization-retry 场景，不回迁目录或重新执行 lifecycle。

执行步骤

1. 验证任务存在

检查任务是否存在于 <task-workspace>/active/{task-id}/。

注意：{task-id} 格式为 TASK-{yyyyMMdd-HHmmss}，例如 TASK-20260306-143022

如果在 active/ 中未找到，检查 blocked/ 和 completed/：

• 如果在 completed/ 且 task.md 存在匹配的 Complete Task Activity Log：进入场景 B finalization-retry，跳过步骤 2-6，直接执行步骤 7
• 如果在 completed/ 但缺少匹配日志：告知用户任务已完成但终态身份不完整并停止，不手工修补
• 如果在 blocked/：告知用户任务被阻塞；建议先解除阻塞

场景 A 为 active 任务的正常完成路径；场景 B finalization-retry 重试允许的 artifact 回填、终态 task 评论、完成校验和摘要封口，不回迁生命周期。

2. 验证完成前置条件（未满足则必须停止）

先读取 reference/external-delivery.md，然后在 active 任务上调用：

agent-infra-internal platform-pr resolve-external {task-id} --agent {standard-agent-token} [--pr {external-pr}]

• mode=external：只以本次 typed result 的 authorization 和 selected 作为外部交付授权与绑定身份，继续 required-PR、本地生命周期和终态校验；外围证据失败在 lifecycle 后记录为 warning。
• mode=normal：走现有本地生命周期前置条件；历史 PR 字段不构成外部授权。
• status=failed|blocked：立即停止并展示稳定错误；--force 不得绕过。

门控读取（项目级 PR 流程策略）：在执行本步骤前，读取 .agents/.airc.json 的 prFlow 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；"required" = 强制 PR；"disabled" = 强制无 PR），以及 task.md frontmatter 的 pr_delivery_fact（unbound / bound / skipped）。

PR 维度判定（先判 prFlow 强约束，后看 pr_delivery_fact.state）：

• --skip-pr 处理：仅在 prFlow 非 required 时生效——通过当前 platform-pr skip 写入器把 task.md 的 pr_delivery_fact.state 写为 skipped 后继续；prFlow=required 时忽略 --skip-pr 并按上表停止。
• 注：--force 可越过下方其余前置条件，但不解除 prFlow=required 的 PR 强约束（强约束的唯一出口是创建 PR）。

缺省 + pending 的二选一引导消息：

任务 {task-id} 尚未决定 PR 交付（pr_delivery_fact: unbound）。请二选一：
  - 走 PR 流程：/create-pr --task {task-ref}
  - 显式跳过并完成：/complete-task --task {task-ref} --skip-pr

required + pending/skipped 的停止消息：

当前项目强制 PR 流程（prFlow: "required"），任务尚未创建 PR。
请先运行 /create-pr --task {task-ref} 创建 PR 后再完成；--skip-pr 在强制 PR 下不被接受。

生命周期前只验证硬门禁：

• task 身份、active 状态校验和本地原子生命周期操作可用
• prFlow=required 时已满足 required-PR delivery
• 其余业务证据（工作流、审查、提交、测试、分歧账本、人工校验和平台同步）已记录或可在生命周期后校验；人工验证只能由 committed transaction、receipt、当前 artifact 摘要和带 identity 的通过日志满足

⚠️ 前置条件分支判断 — 你必须先判断“继续”还是“停止”：

• 如果硬门禁满足 → 继续步骤 3
• 如果硬门禁不满足 → 停止并输出前置条件未满足的警告
• 外围业务证据不满足不阻止生命周期；在生命周期后以 warning/pending steps 表示

禁止在前置条件未满足时继续执行步骤 3-8，也不要输出「任务 {task-id} 已完成，任务目录已转移到 completed/。」

如果硬门禁未满足，警告用户：

Cannot complete task {task-id} - prerequisites not met:
- [ ] {缺失的前置条件}

Please satisfy the hard prerequisite first, then retry complete-task.

如果硬门禁未满足，立即停止，不执行步骤 3-8。

3. 完成业务内容更新

在 <task-workspace>/active/{task-id}/task.md 中只更新生命周期核心不负责的业务内容：

• 新增或更新 ## 状态核对 段，记录第 0 步审计命令、任务/产物范围、关键结果和未覆盖部分；正常成功不复制完整目录清单或 task.md 尾部，失败、阻塞、身份不一致或争议时附决定性原文行，放在 ## 活动日志 之前
• 标记所有工作流步骤为已完成
• 逐项验证并勾选 ## 完成检查清单 中的所有条目（将 - [ ] 改为 - [x]）

不得在本步骤写 status/current_step/completed_at/updated_at/agent_infra_version、基础 Activity Log、目录或短号；这些由步骤 6 统一提交。

4. 在 active 阶段同步平台

检查 task.md 中是否存在有效的 platform_issue_identity。如果没有，跳过本步骤且不输出任何内容。

Issue 元数据边界见 .agents/rules/issue-sync.md；评论同步统一调用 internal platform intent。

如果存在有效的 platform_issue_identity，严格按以下顺序执行：

1. 调用 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --requirements --fields。
2. 把完成摘要字段写成 JSON 临时文件，并调用 agent-infra-internal platform-comment stage-summary {task-id} --body-file {path}。字段为 taskId、title、summary、artifacts、verification:{state,detail}；taskId 必须是当前完整任务 ID，title 来自 task.md，artifacts 来自当前 artifact registry（无产物用 []）。验证尚未执行时写 state:"not-run" 和非空说明，不等待之后的终态事件或最终验证。命令把规范 payload 与摘要写入 durable staging record；本步骤不得直接发布 summary 评论。

summary 字段只记录当前任务证据能够支持的交付结果、关联 PR 与实际合入事实、验证命令及其范围/结果/未覆盖部分，以及已知待办；需要说明验证范围时可注明对应提交。没有证据支持的事实不推断，未完成事项写入待办。这是 Issue 收尾摘要，不是 PR 留言。

摘要默认使用当前技能的语言：中文技能生成中文摘要，英文技能生成英文摘要。中英文摘要保持相同字段结构。

在暂存前核对正文：删除候选和待收尾占位；不写本地短号、无关窗口/模型/receipt 操作流水或外层已有的完整 TASK-ID。不要删除或改写平台维护的评论 marker 和恢复 metadata；与产品行为有关的路径可按需保留。摘要不预测 Complete Task 的 finalization 终态，也不声称任务已完成或已归档。任务目标状态止于 completed，不默认追加 Archive Tasks；生命周期终态及 warning 由正式 task 评论和 receipt 承担。

stage-summary 用于任务仍处于 active 时暂存摘要。任务进入 completed 后，不要假定该命令仍可用。若 finalization 结果表明已发布的交付事实需要更正，先确认现有受支持的评论同步入口允许在当前状态执行；不支持时，在最终汇报中如实说明限制，不新增入口或改变调用时序。

若账本含合法的 PRC-N post-review 豁免，摘要正文必须镜像 task.md 中的裁决理由、提交范围、人工身份与时间，并明确这是人工覆盖而非自动校验成功。已有匹配 workflow warning 时，同时镜像其原始 failure code/message；尚无 warning 时只写“裁决已记录、最终门禁待验证”，不得提前宣称豁免已通过。summary marker 仍由同一 --kind summary intent 唯一维护。

不要在本步骤同步 task 评论；它依赖 lifecycle 写入后的完整终态 task.md。不要设置 status: label，平台自动化应在 Issue 关闭后清理状态标签。

任一操作失败时，任务仍必须位于 active 且短号仍有效；按失败类型调用以下结构化 warning intent，随后继续步骤 5。平台失败不会阻止本地生命周期。

agent-infra-internal task-warning {task-id} add --step complete-task --severity ACTION_REQUIRED --code {REQUIREMENTS_SYNC_FAILED|SUMMARY_SYNC_FAILED|NETWORK_RETRY_EXHAUSTED} --target {issue|summary|platform} --message "{error_code}: {error_message}" --action "修复平台同步问题后重跑 complete-task"

相同 step/code/target 组合由核心幂等去重；调用方不分配 warning id 或手写账本行。

5. 运行 active 预完成硬门禁

平台写入成功后、移动目录前运行：

agent-infra-internal task-verify {task-id} complete-task.preflight --format text

按 .agents/rules/validation-output.md 展示当次校验摘要；失败、阻塞和软警告保留必要诊断。

该事件只执行 required-PR delivery hard preflight；身份校验和本地原子性仍由宿主 finalization 强制执行。外围 review/manual/platform 检查在 lifecycle 后由 complete-task.completed 处理，并投影为 warning/pending steps。硬门禁退出码非 0（fail/blocked）时，任务继续留在 active，记录稳定 code/target 后停止。

若需要在摘要中镜像 post-review-commit 的 human-decided exemption，在步骤 4 尽力同步原始 failure code/message、PRC id/evidence 和裁决信息；同步失败只记录 SUMMARY_SYNC_FAILED warning，仍继续生命周期。最终是否完成由生命周期后的 terminal verification 决定。

--force 不能解除身份校验、本地原子性或 required-PR hard gate；这些能力失败时必须停止。其余审查、人工校验和平台证据由 terminal verification 记录为 warning/pending，并通过后续重试恢复。

6. 执行宿主 finalization 入口

agent-infra-internal task-finalization {task-id} complete --agent {standard-agent-token}

active 任务的 finalization 先恢复账本中的待处理平台操作，并将 delivery_base_ref 对应的 Issue in: 标签与需求、Issue Type、字段一并同步及复读。任一必要事实无法确认时保持 active，不提交完成状态。

finalization 按允许的 artifact backfill → lifecycle → task 评论 → core verification → warning task 评论更新 → summary seal 的固定顺序执行。每项实际运行的 backfill 必须取得成功终态，否则不得进入 lifecycle；完整 receipt 且无恢复事实的普通重入不执行 backfill、评论、验证或 summary。任何可能写入 managed comment 的 completed 恢复会先把 done summary 持久化为 pending，恢复末尾才重新 seal。summary seal 始终读取任务目录中保留的 durable staging record；平台入口负责校验 marker、owner 和 digest，必要时删除并重建摘要，再复读最终远端顺序。result=completed 即表示宿主已依据结构化结果和 receipt 安全完成；若还有外围 warning 或 pending step，返回 result=completed_with_warnings、warnings 和 pending steps。result=failed 或 result=blocked 仅用于硬失败或 receipt/capability 失败，修复原因后以同一入口重试，不得宣称完成或手工补写局部状态。沙箱不得从旧挂载执行 ls completed 或本地终态校验来重新裁决该结果。

7. 处理 finalization 结果

sandbox-local 入口直接执行已有 finalization prepare/commit。lifecycle 移动前，它先停止本任务 broker 接收新请求，并等待已接收操作按原路径完成；只有 broker owner 退出后才开始迁移 task 目录。成功时消费本次命令返回的结构化结果和 receipt。失败或阻塞时保留源数据与 receipt，按返回的错误处理，不输出完成消息，也不手工改写终态。

complete 保留短号映射。它只会在受管 sandbox 清理确认容器已删除且清理成功后释放。需要清理时可用保留短号或完整 {task-id} 调用 ai sandbox rm；不要在 complete 中单独释放短号。

8. 告知用户

仅在校验通过后执行本步骤。

可选沙箱清理提示（门控渲染）：仅当同时满足 (1) .agents/.airc.json 存在 sandbox 字段、(2) task.md 的 branch 字段存在且不是 main / master 时，才渲染下方输出中的「可选：清理本任务的沙箱」块；任一不满足则整段省略。清理时使用完整 {task-id}，不要改用 branch 名。该块独立于「下一步」语义，不是工作流后继命令。

输出格式：

任务 {task-id} 已完成，任务目录已转移到 completed/。

任务信息：
- 标题：{title}
- 完成时间：{timestamp}
- 目标路径：<task-workspace>/completed/{task-id}/

交付物：
- {关键产出列表：修改的文件、添加的测试等}

可选：清理本任务的沙箱
（任务已完成，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）

ai sandbox rm {task-id}  # 或使用本任务仍保留的短号

完成检查清单

• 满足了硬性前置条件并通过预完成门禁
• 宿主 finalization 返回 result=completed 或 result=completed_with_warnings
• 完成校验通过
• 已向用户报告结构化完成结果和适用的警告

注意事项

• 如果多个 AI 代理参与任务，确保所有贡献都包含在本地 checkpoint 中。

错误处理

• 任务未找到：提示 "Task {task-id} not found in active directory"
• 已完成：仅当存在匹配的 Complete Task Activity Log 时进入 finalization-retry；否则说明终态身份不完整并停止
• 任务被阻塞：满足记录的解除条件后，通过 task-lifecycle activate 恢复任务，再重试
• finalization 失败或阻塞：保留源数据和 receipt，根据结构化错误通过同一 finalization 入口恢复；不要手工改写终态或移动任务目录