complete-task

name	complete-task
description	标记任务完成并归档。 当任务工作已完成并验证、需要收尾归档时使用。

完成任务

行为边界 / 关键规则

• 本命令更新任务元数据并物理移动任务目录
• 除非强制执行，不要转移有未完成工作流步骤的任务

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

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

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

运行以下命令，并把原文粘贴到回复正文和本轮产物的 ## 状态核对 段：

git status -s
ls -la .agents/workspace/active/{task-id}/
tail .agents/workspace/active/{task-id}/task.md

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

任务入参短号别名

如果 {task-id} 入参匹配 ^[#]?[0-9]+$（裸数字或带 # 前缀），先读取 .agents/rules/task-short-id.md 的「SKILL 入参解析」段执行解析；后续命令视 {task-id} 为解析后的全长 TASK-YYYYMMDD-HHMMSS 形式。

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

确认任务存在并通过预完成门禁后，由步骤 4 的单次 lifecycle intent 原子完成基础终态字段、started/done 日志、目录转移和短号释放；不得提前手工写入这些机械状态。

执行步骤

1. 验证任务存在

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

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

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

• 如果在 completed/：告知用户任务已完成
• 如果在 blocked/：告知用户任务被阻塞；建议先解除阻塞

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

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

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

prFlow	pr_status	判定
disabled	任意	无 PR 路径 → PR 维度满足，继续其余前置条件
required	created	PR 维度满足，继续
required	pending / skipped	停止：强制 PR 下必须先 /create-pr；--skip-pr 不被接受（含既有/手动写入的 skipped）
缺省	created / skipped	PR 维度满足，继续
缺省	pending	默认停止并输出下方二选一引导；除非用户提供 --skip-pr（写 pr_status: skipped 后继续）或 --force

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

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

任务 {task-id} 尚未创建 PR（pr_status: pending）。请二选一：
  - 走 PR 流程：/create-pr {task-ref}
  - 显式跳过并完成：/complete-task {task-ref} --skip-pr

required + pending/skipped 的停止消息：

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

标记完成之前，验证以下所有条件：

• 所有工作流步骤已完成（检查 task.md 中的工作流进度；对 yaml 中 commit 步骤的 pr_tasks 列表，按「走 PR 路径」判定是否计入未完成判定：prFlow=required 始终计入；prFlow=disabled 不计入；缺省下仅当 pr_status=skipped 时不计入，否则计入）
• 代码已审查（review-code.md 或 review-code-r{N}.md 存在，且最新审查结论为 Approved；或已在外部完成审查）
• 代码已提交（没有与此任务相关的未提交变更）
• 测试通过
• 审查分歧账本无未关闭分歧，且无未复审的 post-review 提交（由下方「预完成硬门禁」机械校验）

预完成硬门禁（在移动目录、释放短号之前运行）：步骤 7 的 gate complete-task 在目录已 mv 到 completed/、短号已释放之后才运行；为避免门禁失败发生在不可逆操作之后，必须在 active 目录上预先运行新增的两项完成门禁：

node .agents/scripts/validate-artifact.js check review-ledger .agents/workspace/active/{task-id} --skill complete-task --format text
node .agents/scripts/validate-artifact.js check post-review-commit .agents/workspace/active/{task-id} --skill complete-task --format text

任一退出码非 0（fail/blocked）→ 按前置条件未满足处理，停止，不执行步骤 3-7。若输出包含 reviewed snapshot was not anchored，必须先重新 commit 或 review-code；不得回退审查基线。--force 不解除本硬门禁：未关闭分歧必须先在账本闭合（confirmed/closed/human-decided），已锚点后的未复审提交必须重新 review-code 或在账本追加 post-review-commit / human-decided 豁免行。

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

• 如果以上所有条件都满足 → 继续步骤 3
• 如果任意一个条件不满足 → 默认停止，输出前置条件未满足的警告
• 只有用户明确要求 --force 时，才可以在前置条件未满足时继续

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

如果任何前置条件未满足，警告用户：

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

Please complete the missing steps first, or use --force to override.

如果前置条件未满足且用户未明确提供 --force，立即停止，不执行步骤 3-7。

3. 完成业务内容更新

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

• 新增或更新 ## 状态核对 段，粘贴第 0 步审计命令原文（含 $ 前缀行），放在 ## 活动日志 之前
• 标记所有工作流步骤为已完成
• 逐项验证并勾选 ## 完成检查清单 中的所有条目（将 - [ ] 改为 - [x]）

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

4. 执行本地生命周期意图

agent-infra-internal task-lifecycle {task-id} complete --agent {agent}

仅 status=applied|no-op 视为本地完成。status=failed 时展示 error 与 completed/pending steps，以同一 intent 重试；不得宣称完成或手工补写局部状态。

5. 验证转移

ls .agents/workspace/completed/{task-id}/task.md

确认任务目录已成功移动。

6. 同步到 Issue

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

Issue 同步规则见 .agents/rules/issue-sync.md。执行同步前先读取该文件，完成 upstream 仓库检测和权限检测。

如果存在有效的 issue_number：

• 先按 .agents/rules/issue-sync.md 的补发规则扫描并补发未发布的 task.md、analysis*.md、review-analysis*.md、plan*.md、review-plan*.md、code*.md、review-code*.md 评论（task.md 走幂等更新路径）
• 按 issue-sync.md 的需求复选框同步步骤，兜底同步 ## 需求 中已勾选的条目到 Issue body
• 不要设置 status: label — 平台自动化应在 Issue 关闭后清理状态标签；预完成 platform-sync gate 会验证 CLOSED Issue 不含任何 status: 标签，残留时失败并要求等待或修复 workflow 后重跑
• 最后创建或更新 .agents/rules/issue-sync.md 中定义的 summary 评论标记对应的 summary 评论
• 读取 .agents/rules/issue-fields.md，按流程 A 把 task.md 中所有非空的 Issue 字段（priority/effort/start_date/target_date）同步到 Issue（幂等；has_push=false 或取数/写入失败时跳过，不阻断）

7. 完成校验

运行完成校验，确认任务产物和同步状态符合规范：

node .agents/scripts/validate-artifact.js gate complete-task .agents/workspace/completed/{task-id} --format text

处理结果：

• 退出码 0（全部通过）-> 继续到「告知用户」步骤
• 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
• 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入

将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。

8. 告知用户

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

完成时间收尾行（整段输出的最后一行）取值 date "+%Y-%m-%d %H:%M:%S"（本地时区、不带偏移），固定放在输出的绝对末尾，便于多窗口扫视。本 skill 不渲染「下一步」命令，但会在收尾行之前渲染一段可选的沙箱清理提示（见下方门控），且仍统一打印该收尾行。

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

输出格式：

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

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

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

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

ai sandbox rm {branch}

Completed at: {completion-time}

完成检查清单

• 验证了所有工作流步骤已完成
• 更新了 task.md 的完成状态和时间戳
• 将任务目录移动到 .agents/workspace/completed/
• 验证了转移成功
• 告知了用户完成情况

注意事项

1. 过早完成：不要转移有未完成步骤的任务。未完成的情况示例：

   • 代码已编写但未提交
   • 代码已提交但未审查
   • 审查发现阻塞项但未修复
   • PR 已创建但未合并

2. 回滚：如果任务被错误转移：

   mv .agents/workspace/completed/{task-id} .agents/workspace/active/{task-id}
   

   然后将 task.md 中的状态改回 active。

3. 多贡献者：如果多个 AI 代理参与了任务，确保所有贡献都已提交后再完成。

错误处理

• 任务未找到：提示 "Task {task-id} not found in active directory"
• 已完成：提示 "Task {task-id} is already in completed directory"
• 任务被阻塞：提示 "Task {task-id} is blocked. Unblock it first by moving to active/"
• 移动失败：提示错误并建议手动移动