ln-400-story-executor

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

类型： L2 协调器 类别： 4XX 执行

Story 执行编排器

由运行时支持的 Story 执行协调器。负责任务排序、工作树生命周期、任务／分组检查点，以及最终将 Story 转换为 To Review。

输入

输入	必填	来源	描述
storyId	是	args、git branch、看板、用户	要处理的 Story
--rework-focus	否	ln-1000	来自先前质量门禁 FAIL 的逗号分隔阻塞类别

解析： Story 解析链。
状态筛选： Todo、In Progress、To Rework、To Review

目的与范围

• 每轮仅加载一次 Story 和任务元数据
• 按顺序执行：To Review -> To Rework -> Todo
• 仅在明确标记时启动 Todo 并行分组
• 每次执行器／返工步骤后立即强制进行审查
• 将可恢复的运行时状态持久化到 .hex-skills/story-execution/runtime/
• 仅将 Story 移至 To Review；绝不移至 Done

运行时契约

必须读取： 加载 references/environment_state_contract.md、references/storage_mode_detection.md、references/input_resolution_pattern.md 必须读取： 加载 references/coordinator_runtime_contract.md、references/story_execution_runtime_contract.md、references/coordinator_summary_contract.md、references/loop_health_contract.md 必须读取： 加载 references/git_worktree_fallback.md — 使用 Story 执行行

运行时 CLI：

node references/scripts/story-execution-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-execution/manifest.json
node references/scripts/story-execution-runtime/cli.mjs status
node references/scripts/story-execution-runtime/cli.mjs checkpoint --phase PHASE_3_SELECT_WORK --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-worker --task-id {taskId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-group --group-id {groupId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-stage-summary --story {storyId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-loop-health --scope task --scope-id {taskId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs advance --to PHASE_4_TASK_EXECUTION

工作流

阶段 0：配置

1. 解析 storyId。
2. 从任务管理配置中检测 task_provider。
3. 构建执行清单：
   • story_id
   • task_provider
   • project_root
   • 计划的 worktree_dir
   • 分支名称
   • parallel_group_policy
   • status_transition_policy
4. 启动运行时并创建检查点 PHASE_0_CONFIG。

阶段 1：发现

1. 解析 Story 标题和当前 Story 状态。
2. 仅加载子任务元数据：
   • 使用已配置的跟踪器提供方的 listTasksByStory(storyId) 操作（传输方式参见 references/provider_file.md, references/provider_github.md, references/provider_linear.md）。
3. 构建以下项目的 processable_counts：
   • to_review
   • to_rework
   • todo
4. 创建检查点 PHASE_1_DISCOVERY。

阶段 2：工作树设置

1. 检测当前分支。
2. 如果已经位于 feature/* 中，则将当前目录视为活动工作树。
3. 否则，按照工作树回退指南创建 .hex-skills/worktrees/story-{identifier} 和分支 feature/{identifier}-{slug}。
4. 创建检查点 PHASE_2_WORKTREE_SETUP，包含：
   • worktree_ready
   • worktree_dir
   • branch
5. 仅在 worktree_ready=true 后继续。

阶段 3：选择工作

选择顺序是确定的：

1. 优先处理任何 To Review 任务，按顺序逐个处理
2. 然后处理任何 To Rework 任务，按顺序逐个处理
3. 然后处理 Todo 任务：
   • 带有 **Parallel Group:** {N} 的任务可作为一个分组运行
   • 未分组的任务作为单任务顺序单元

创建 PHASE_3_SELECT_WORK 检查点，包含：

• current_task_id 或 current_group_id
• 最新的 processable_counts

如果所有可处理计数均为零，则跳过执行并进入 PHASE_7_STORY_TO_REVIEW。

提供 rework_focus 时：

• 标题或 AC 关键词与任一 blocking_categories 条目匹配的任务，将在同一优先级层级内优先选择。
• 这不会覆盖 To Review > To Rework > Todo 的顺序 — 仅在各层级内重新排序。

阶段 4：任务执行

适用于：

• To Review -> ln-402
• To Rework -> ln-403，然后立即执行 ln-402
• 单个 Todo 测试任务 -> ln-404，然后立即执行 ln-402
• 单个 Todo 实现/重构任务 -> ln-401，然后立即执行 ln-402

流程：

1. 计算执行器 childRunId = {parent_run_id}--{worker}--{taskId}。
2. 计算执行器产物路径 .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json。
3. 在 .hex-skills/story-execution/{worker}--{taskId}_manifest.json 中生成执行器清单。
4. 启动 task-worker-runtime，并在调用前记录执行器 child_run 元数据检查点。
5. 通过 Agent 或 Skill 执行工作器，并使用 --run-id 和 --summary-artifact-path。
6. 从 .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json 读取执行器摘要产物。
7. 重试相同任务/工作器/错误前，记录任务循环健康状况：
   • 操作：将当前工作器输出与之前的任务循环健康状况进行比较。
   • 要点：仅当存在新产物、新的 ln-402 摘要、任务状态变化、files_changed 变化或场景改善时才重试。
   • 原因：重复相同的工作器故障会造成重试风暴，却不会增加证据。
   • 证据：record-loop-health --scope task --scope-id {taskId} 结果。
   • 例外：如果 pause.pause=true，则停止并显示 paused_reason。
   • 自动化/保护措施：story-execution runtime 会在达到相同错误/无进展阈值后暂停。
8. 需要审核时，对 ln-402 重复相同的运行时支持流程。
9. 从 .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--ln-402.json 读取同一任务最新的 ln-402 审核摘要产物。
10. 使用 record-worker 记录工作器产物。
11. 记录 PHASE_4_TASK_EXECUTION 检查点。
12. 进入 PHASE_6_VERIFY_STATUSES。

阶段 5：分组执行

仅适用于包含多个任务的 Todo 组。

1. 为每项任务计算特定于工作器的子 runId、产物路径和清单路径。
2. 为每个执行器启动一个 task-worker-runtime，并在生成 Agent 前记录所有子项元数据检查点。
3. 通过 Agent 工具并行启动所有组执行器。
4. 等待所有执行器完成。
5. 读取每个执行器的摘要产物。
6. 为每项任务启动一个 ln-402 runtime，依次审核每项任务，并读取每项任务的最新审核产物。
7. 使用 record-worker 记录每个工作器产物，然后使用 record-group 记录组摘要。
8. 记录 PHASE_5_GROUP_EXECUTION 检查点。
9. 进入 PHASE_6_VERIFY_STATUSES。

阶段 6：验证状态

1. 从事实来源重新读取任务元数据。
2. 刷新 processable_counts。
3. 验证本次运行中涉及的每项任务都具有最新的 ln-402 机器可读摘要。
4. 如果任何工作器产生意外的状态转换，则暂停 runtime。
5. 如果任何任务连续第三次进入 To Rework，则暂停 runtime 并提供升级原因。
6. 记录 PHASE_6_VERIFY_STATUSES 检查点。
7. 如果仍有可处理的工作 -> 返回 PHASE_3_SELECT_WORK。
8. 如果没有可处理的工作 -> 进入 PHASE_6B_SCENARIO_VALIDATION。

场景验证

所有任务均为 Done 后运行一次。委派给外部 Agent，根据已实现的代码端到端追踪用户场景。执行者在引导任务完成实现后容易产生完成偏差——外部 Agent 并未投入精力推动故事完成。

1. 加载 Story AC 和可追溯性表（来自 .hex-skills/task-planning/{identifier}_traceability.md）。如果缺少可追溯性产物，请根据 Story AC 和任务实施计划重建等效追踪；不要仅因规划器产物缺失而导致场景验证失败。

2. 运行 Agent 健康检查。如果有可用的顾问 Agent： a. 根据 references/agents/prompt_templates/scenario_validator.md 构建验证提示词 b. 填入：Story AC、可追溯性表、架构上下文、项目根目录路径（Agent 会直接读取代码） c. 将提示词保存到 .hex-skills/story-execution/{identifier}_scenario_prompt.md d. 启动 Agent：

   node references/agents/agent_runner.mjs \
     --agent {agent} \
     --prompt-file .hex-skills/story-execution/{identifier}_scenario_prompt.md \
     --output-file .hex-skills/story-execution/{identifier}_scenario_result.md \
     --cwd {project_dir}
   

   e. 解析结果 JSON，找出存在问题的片段

3. 如果没有可用的 Agent：以自检作为后备方案（通过代码检查追踪 5 个片段）。

4. 如果有任何片段存在问题或缺失：

   • 根据可追溯性表中的层级映射确定负责的任务
   • 在再次设置返工前，按存在问题的片段记录场景循环状态
   • 如果同一存在问题的片段再次出现，且代码/产物没有变化，则暂停，不要盲目返工
   • 将该任务状态设回 To Rework，并将场景发现作为返工上下文
   • 返回 PHASE_3_SELECT_WORK

5. 场景验证循环最多 2 次。如果 2 次返工循环后仍未通过，则 PAUSE，等待用户审核。

6. 如果所有片段均通过 -> 前进至 PHASE_7_STORY_TO_REVIEW。

检查点 PHASE_6B_SCENARIO_VALIDATION 包含：

• scenario_pass：true/false
• segments_traced：追踪的片段数
• segments_passed：通过的片段数
• rework_tasks：送回返工的任务 ID 列表（通过时为空）
• validation_mode：agent_validated 或 self_check_only

阶段 7：将 Story 送审

1. 确认没有任务仍处于 Todo、To Review 或 To Rework 状态。
2. 将 Story 状态更新为 To Review。
3. 将看板状态更新为 To Review。
4. 设置检查点 PHASE_7_STORY_TO_REVIEW，包含：
   • story_transition_done=true
   • story_final_status="To Review"
   • final_result="READY_FOR_GATE"
5. 编写阶段 2 协调器产物，包含：
   • summary_kind=pipeline-stage
   • stage=2
   • story_id
   • status=completed
   • final_result="READY_FOR_GATE"
   • story_status="To Review"
   • warnings

阶段 8：自检

根据运行时状态而非记忆，构建最终检查清单：

• 配置检查点存在
• 探索检查点存在
• 工作树检查点存在，且 worktree_ready=true
• 每个已执行的任务都有最新的 ln-402 摘要产物
• 每个已处理的组都有记录的运行时结果
• 返工循环保护机制未触发
• Story 已转为 To Review
• 阶段 2 协调器产物已记录

设置检查点 PHASE_8_SELF_CHECK，并令 pass=true|false。 只有在 pass=true 后才能完成运行时流程。

Worker 调用（强制）

宿主 Skill 调用： 必须委派调用 Skill(skill: "...", args: "...")。

• Claude：必须严格按所示方式调用 Skill 工具。
• Codex：如果没有 Skill 工具，请在可用的技能中找到指定技能，读取其 SKILL.md，将 args 视为 $ARGUMENTS，执行该技能工作流，然后携带其结果/产物返回此处。
• 不要内联 Worker 逻辑，也不要在未执行目标技能的情况下将 Worker 标记为完成。

状态	Worker	调用方式
To Review	ln-402-task-reviewer	通过 Skill() 内联调用
To Rework	ln-403-task-rework	Agent，然后立即运行 ln-402
Todo 测试	ln-404-test-executor	Agent，然后立即运行 ln-402
Todo 实现/重构	ln-401-task-executor	Agent，然后立即运行 ln-402

执行者和返工者在隔离环境中运行：

node references/scripts/task-worker-runtime/cli.mjs start --skill {worker} --task-id {taskId} --manifest-file .hex-skills/story-execution/{worker}--{taskId}_manifest.json --run-id {childRunId} --summary-artifact-path .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json
node references/scripts/story-execution-runtime/cli.mjs checkpoint --phase PHASE_4_TASK_EXECUTION --payload '{"child_run":{"worker":"{worker}","task_id":"{taskId}","run_id":"{childRunId}","summary_artifact_path":".hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json"}}'
Agent(
  description: "Execute task {taskId}",
  prompt: "Execute task worker.\n\nStep 1: Invoke worker:\n  Skill(skill: \"{worker}\", args: \"{taskId} --run-id {childRunId} --summary-artifact-path .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json\")\n\nCONTEXT:\nTask ID: {taskId}",
  subagent_type: "general-purpose"
)

审核者以内联方式运行：

node references/scripts/task-worker-runtime/cli.mjs start --skill ln-402 --task-id {taskId} --manifest-file .hex-skills/story-execution/ln-402--{taskId}_manifest.json --run-id {reviewRunId} --summary-artifact-path .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--ln-402.json
node references/scripts/story-execution-runtime/cli.mjs checkpoint --phase PHASE_4_TASK_EXECUTION --payload '{"child_run":{"worker":"ln-402","task_id":"{taskId}","run_id":"{reviewRunId}","summary_artifact_path":".hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--ln-402.json"}}'
Skill(skill: "ln-402-task-reviewer", args: "{taskId} --run-id {reviewRunId} --summary-artifact-path .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--ln-402.json")

TodoWrite 格式（必需）

- Start ln-400 runtime (pending)
- Load Story/task metadata (pending)
- Setup or detect worktree (pending)
- Select next task/group (pending)
- Start child runtime(s) and checkpoint child metadata (pending)
- Execute task/group with managed transport inputs (pending)
- Review task results immediately (pending)
- Re-read statuses and record checkpoint (pending)
- Validate user scenario end-to-end (pending)
- Move Story to To Review (pending)
- Run runtime self-check and complete (pending)

关键规则

• 运行时状态是编排的 SSOT；看板是任务状态的 SSOT。
• 不得批量评审。
• 不得将 Story 移至 Done。
• 必须从摘要 JSON 中读取每个工作者的结果，而非仅从聊天文本中读取。
• record-worker 是工作者结果的主要运行时录入路径。
• 在重复执行任务／任务组／场景工作之前，record-loop-health 是重试有效性的主要录入路径。
• 每次受管工作者运行都必须先通过 task-worker-runtime 启动，然后才能调用。
• ln-1000 使用 Stage 2 协调器产物，而非自由文本阶段输出。
• 即使执行组并行运行，评审仍须按顺序进行。
• 只有 ln-402 可以接受将任务设为 Done。

完成定义

• 已启动运行时并记录 PHASE_0_CONFIG 检查点
• 已记录发现和工作树设置检查点
• 已在运行时记录每个已执行的任务／任务组
• 在需要时以确定方式处理返工循环升级（PAUSED）
• 已记录最终状态验证检查点
• 场景验证已通过，或已暂停（PAUSED）以供用户评审
• Story 已移至 To Review，而非 Done
• 自检已通过，且运行时已完成

阶段 9：元分析

可选参考：仅当用户要求运行后元分析或采用协议格式的运行反思时，才加载 references/meta_analysis_protocol.md。

技能类型：execution-orchestrator。收到请求时，在各阶段完成后运行。使用 execution-orchestrator 格式在聊天中输出。

参考文件

• references/coordinator_runtime_contract.md
• references/story_execution_runtime_contract.md
• references/coordinator_summary_contract.md
• references/git_worktree_fallback.md
• ../ln-401-task-executor/SKILL.md
• ../ln-402-task-reviewer/SKILL.md
• ../ln-403-task-rework/SKILL.md
• ../ln-404-test-executor/SKILL.md

---

版本： 4.0.0 最后更新： 2026-01-29