block-task

标记任务阻塞

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

行为边界 / 关键规则

• 本命令更新任务元数据并物理移动任务目录
• 仅在确实无法继续时才阻塞 —— 如果是可以克服的困难，先尝试解决

使用场景

• 技术问题：无法解决的 Bug、缺少依赖、基础设施问题
• 需求问题：需求不明确、规格冲突、待定决策
• 资源问题：缺少访问权限、等待外部团队、被其他任务阻塞
• 需要决策：待定的架构决策、需要利益相关者批准

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

任务上下文解析

入口可省略 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；无法定位时按未找到任务处理并停止。

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

确认前置条件后，由步骤 3 的单次 lifecycle intent 原子写入 started/done 日志、基础元数据、目录转移和短号释放；本步骤不得提前手工写入其中任一项。

执行步骤

1. 验证任务存在

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

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

如果未找到，检查其他目录并告知用户。

2. 分析阻塞原因

阻塞之前，彻底分析：

• 具体的问题是什么？
• 根本原因是什么？
• 已经尝试了哪些解决方案？
• 需要什么帮助或信息才能解除阻塞？

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

agent-infra-internal task-lifecycle {task-id} block --agent {standard-agent-token} \
  --reason "{一行原因}" --unblock-condition "{解除阻塞条件}"

解析 stdout 单 JSON。仅 status=applied|no-op 视为本地完成；status=failed 时展示 error 与 completedSteps/pendingSteps，不得宣称任务已阻塞。生命周期核心统一维护 status/blocked_at、阻塞信息、Activity Log、目录与短号。

4. 验证本地终态

确认结构化结果的 targetState=blocked、目标路径为 .agents/workspace/blocked/{task-id}、短号效果已提交，并检查：

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

5. 保留恢复身份

记录 lifecycle 结果中的请求身份与规范 metadata，供失败后以同一 intent 安全重试；不得手工补写局部状态。

6. 同步到 Issue（可选）

检查 task.md 中是否存在有效的 issue_number。如果没有，跳过。

如果存在有效的 issue_number，调用 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status blocked。 随后调用 agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token} 更新 task 评论。