ln-500-story-quality-gate

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

类型： L2 协调器 类别： 5XX 质量

Story 质量门禁

由运行时支持的门禁协调器。负责快速通道路由、质量／测试摘要、最终 Story 判定以及分支收尾。

输入

输入	必需	来源	描述
storyId	是	args、git 分支、看板、用户	要处理的 Story

解析： Story 解析链。
状态筛选： To Review

目的与范围

• 调用 ln-510-quality-coordinator
• 必要时调用 ln-520-test-planner
• 确定性地等待测试任务就绪
• 计算门禁判定：PASS | CONCERNS | FAIL | WAIVED
• 仅在结果通过时将 Story 移至 Done
• 在 .hex-skills/story-gate/runtime/ 中持久化可恢复的门禁运行时数据

运行时约定

必须读取： 加载 references/environment_state_contract.md、references/storage_mode_detection.md、references/input_resolution_pattern.md 必须读取： 加载 references/coordinator_runtime_contract.md、references/story_gate_runtime_contract.md、references/coordinator_summary_contract.md、references/loop_health_contract.md 必须读取： 加载 references/git_worktree_fallback.md 必须读取： 加载 references/minimum_quality_checks.md

运行时 CLI：

node references/scripts/story-gate-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/manifest.json
node references/scripts/story-gate-runtime/cli.mjs status
node references/scripts/story-gate-runtime/cli.mjs record-quality --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs record-test-status --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs record-stage-summary --story {storyId} --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs checkpoint --phase PHASE_6_VERDICT --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs advance --to PHASE_7_FINALIZATION

4 级门禁模型

判定	含义	操作
PASS	所有检查均通过	Story -> Done
CONCERNS	存在轻微问题，接受风险	Story -> Done 并添加评论
FAIL	发现阻塞性问题	创建后续任务；Story 不移至 Done
WAIVED	用户批准的例外	Story -> Done 并附上豁免证据

工作流

阶段 0：配置

1. 解析 storyId 和 task_provider。
2. 检查 .hex-skills/runtime-artifacts/runs/*/story-quality/{storyId}.json 中是否存在先前的 Stage 3 产物：
   • 如果找到且 verdict=FAIL，则将 payload.metadata.rework_hint 加载为 previous_cycle 上下文。
   • 记录 cycle_number（从 1 开始，根据先前产物数量递增）。
3. 构建门禁清单：
   • story_id
   • task_provider
   • project_root
   • worktree_dir
   • branch
   • fast_track_policy
   • nfr_policy
   • test_task_policy
   • previous_cycle（为空或已加载的 rework_hint）
   • cycle_number
4. 启动运行时并创建 PHASE_0_CONFIG 检查点。

阶段 1：发现

1. 加载 Story 元数据和子任务元数据。
2. 检测现有测试任务及其当前状态。
3. 如果上游流水线提供了就绪输入，则予以记录。
4. 创建 PHASE_1_DISCOVERY 检查点。

阶段 2：快速通道

1. 仅在就绪状态明确允许时，才将 fast_track=true。
2. 创建 PHASE_2_FAST_TRACK 检查点，其中包含：
   • fast_track
   • 门禁范围摘要

第 3 阶段：质量检查

1. 计算：
   • childRunId = {parent_run_id}--ln-510--{storyId}
   • childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-quality/{storyId}.json
2. 生成子清单并启动子协调器运行时：
   • node references/scripts/quality-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-510--{storyId}_manifest.json --run-id {childRunId}
3. 使用以下信息创建 PHASE_3_QUALITY_CHECKS 检查点：
   • child_run.worker=ln-510
   • child_run.run_id={childRunId}
   • child_run.summary_artifact_path={childSummaryArtifactPath}
   • child_run.phase_context=quality_checks
4. 使用托管传输输入调用 ln-510-quality-coordinator：
   • 完整模式：Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
   • 快速通道：Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --fast-track --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
   • 带有上一周期的完整模式：当 previous_cycle 不为 null 时，追加 --previous-cycle-focus "{blocking_categories}"
5. 仅读取子级 story-quality 工件，然后执行 record-quality。
6. 在开始下一轮质量检查／返工周期之前，将 FAIL 证据与上一周期进行比较：
   • 有进展 = 新的质量工件、新的修复任务、代码变更、状态变更或阻塞类别变更
   • 相同的 FAIL 且没有新证据 = 记录循环健康状况，并在开始下一轮返工周期前暂停
7. 使用已记录的质量摘要创建 PHASE_3_QUALITY_CHECKS 检查点。
8. 如果质量摘要已表明硬性 FAIL，可以直接跳转到 PHASE_6_VERDICT。

第 4 阶段：测试规划

1. 判断是否需要规划：
   • 没有测试任务 -> 调用 ln-520
   • 快速通道 -> 调用简化版 ln-520
   • 测试任务已存在且处于终态（Done | SKIPPED | VERIFIED）-> 将其作为已复用项创建检查点
2. 调用 ln-520 时，计算：
   • childRunId = {parent_run_id}--ln-520--{storyId}
   • childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-tests/{storyId}.json
3. 生成子清单并启动子协调器运行时：
   • node references/scripts/test-planning-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-520--{storyId}_manifest.json --run-id {childRunId}
4. 使用以下信息创建 PHASE_4_TEST_PLANNING 检查点：
   • child_run.worker=ln-520
   • child_run.run_id={childRunId}
   • child_run.summary_artifact_path={childSummaryArtifactPath}
   • child_run.phase_context=test_planning
5. 使用托管传输输入调用 ln-520-test-planner：
   • 普通模式：Skill(skill: "ln-520-test-planner", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
   • 简化模式：Skill(skill: "ln-520-test-planner", args: "{storyId} --simplified --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
6. 仅读取子级 story-tests 工件，然后执行 record-test-status。
7. 创建 PHASE_4_TEST_PLANNING 检查点。

第 5 阶段：测试验证

1. 如果测试任务存在但尚未处于 Done 状态，则暂停运行时：
   • phase = PAUSED
   • resume_action = wait for test task completion
2. 恢复后，验证：
   • 测试任务的终态为 Done、SKIPPED 或 VERIFIED
   • 覆盖率摘要存在
   • 规划的场景和 Story AC 覆盖情况可由机器读取
3. 使用以下信息创建 PHASE_5_TEST_VERIFICATION 检查点：
   • test_task_status
   • 验证结果

阶段 6：判定

1. 计算 quality_score。
2. 评估 NFR 验证：
   • 完整门禁：安全性、性能、可靠性、可维护性
   • 快速通道：安全性为必选项，其他项可降级为仅关注事项
3. 端到端场景完整性演练： 对于每项必须由某个参与者（用户、机器人、调度程序、处理程序、流水线）调用或使用某种机制的 AC，追踪交互路径的全部 5 个环节：
   • (1) 参与者触发 — 什么会启动该场景（用户发送消息、计时器触发、webhook 到达、事件入队）
   • (2) 入口点 — 命名的机制（MCP 工具、API 端点、CLI 命令、UI 组件、聊天处理程序、配置文件、cron 处理程序）
   • (3) 发现 — 参与者的系统在运行时如何找到／加载该机制（配置注册、路由挂载、插件加载、系统提示词、环境变量）
   • (4) 使用上下文 — 参与者的系统正确调用该机制所需的内容（说明、提示词、架构、类型提示、文档、参数指引）
   • (5) 可观察结果 — 可验证的结果（响应消息、状态变更、日志条目、通知） 如果任何环节缺失，则创建一个以 AC- 为前缀的问题。常见失败情况：基础设施存在但没有任何入口暴露它（缺少环节 2）；机制存在但参与者的系统无法找到它（缺少环节 3）；机制可被发现，但参与者的系统不知道何时或如何使用它（缺少环节 4）。如果发现任何 AC- 问题，判定结果必须为 FAIL；为缺失环节创建修复任务。
4. 确定最终判定结果。
5. 对于 FAIL：
   • 创建后续任务
   • 不要将 Story 移至 Done
6. 使用以下内容创建 PHASE_6_VERDICT 检查点：
   • final_result
   • quality_score
   • nfr_validation
   • fix_tasks_created

阶段 7：收尾

对于 PASS | CONCERNS | WAIVED：

1. 如有需要，提交并推送已验证的分支。
2. 将 Story 移至 Done。
3. 发布门禁评论。
4. 如果调用方不拥有工作树，则清理工作树。

对于 FAIL：

1. 不要将分支作为已验收分支完成收尾。
2. 根据阻塞问题创建后续任务。
3. 使用 status=requires_rework 创建 PHASE_7_FINALIZATION 检查点。
4. 记录最终的 Story 状态和后续任务 ID。

收尾后，写入 Stage 3 协调器产物，包含：

• summary_kind=pipeline-stage
• stage=3
• story_id
• status=completed
• final_result
• story_status
• verdict
• quality_score
• warnings
• metadata.rework_hint — 当判定结果为 FAIL 时，包含：
  • rework_tasks：已创建的后续任务 ID 列表
  • blocking_categories：导致 FAIL 的问题类别列表（例如 ac_gap、security、regression）
  • suggested_focus：简洁的一句话，说明返工周期应优先处理的事项

阶段 8：自检

根据运行时状态生成最终检查清单：

• 配置、发现和快速通道检查点均已存在
• 已记录来自 ln-510 的质量摘要
• 测试规划和测试验证状态具有确定性
• 最终判定检查点已存在
• 已记录 Story 的最终状态
• 已记录分支收尾情况，或根据判定结果跳过收尾
• 已记录 Stage 3 协调器产物

使用 pass=true|false 创建 PHASE_8_SELF_CHECK 检查点。 仅在 pass=true 后完成运行时流程。

Worker 调用（强制）

Host Skill 调用： 必须委派执行 Skill(skill: "...", args: "...")。

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

阶段	Worker	用途
3	ln-510-quality-coordinator	代码质量、Agent 审查、回归、日志分析
4	ln-520-test-planner	研究／手动／自动化测试规划

childRunId = "{parent_run_id}--ln-510--{storyId}"
childSummaryArtifactPath = ".hex-skills/runtime-artifacts/runs/{parent_run_id}/story-quality/{storyId}.json"
node references/scripts/quality-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-510--{storyId}_manifest.json --run-id {childRunId}
node references/scripts/story-gate-runtime/cli.mjs checkpoint --phase PHASE_3_QUALITY_CHECKS --payload '{"child_run":{"worker":"ln-510","run_id":"{childRunId}","summary_artifact_path":"{childSummaryArtifactPath}","phase_context":"quality_checks"}}'
Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")

childRunId = "{parent_run_id}--ln-520--{storyId}"
childSummaryArtifactPath = ".hex-skills/runtime-artifacts/runs/{parent_run_id}/story-tests/{storyId}.json"
node references/scripts/test-planning-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-520--{storyId}_manifest.json --run-id {childRunId}
node references/scripts/story-gate-runtime/cli.mjs checkpoint --phase PHASE_4_TEST_PLANNING --payload '{"child_run":{"worker":"ln-520","run_id":"{childRunId}","summary_artifact_path":"{childSummaryArtifactPath}","phase_context":"test_planning"}}'
Skill(skill: "ln-520-test-planner", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")

TodoWrite 格式（强制）

- Start ln-500 runtime (pending)
- Load Story/test-task metadata (pending)
- Decide fast-track mode (pending)
- Start ln-510 child runtime, checkpoint child_run, and record quality summary (pending)
- Start or reuse ln-520 child runtime, checkpoint child_run, and record test-planning summary (pending)
- Verify test task readiness (pending)
- Calculate final verdict (pending)
- Finalize Story/branch state and Stage 3 artifact (pending)
- Run runtime self-check and complete (pending)

关键规则

• 运行时状态是门控编排的 SSOT。
• ln-510 和 ln-520 仅通过摘要 JSON 工件使用。
• 子协调器运行时状态仅作为恢复元数据；阶段是否完成仍取决于记录的子工件。
• 等待测试任务是确定性暂停，而不是隐式停止。
• 如果正确记录了后续操作，FAIL 是有效的终止门控结果。
• ln-1000 使用 Stage 3 协调器工件，而非自由文本阶段输出。
• 只有在 PASS、CONCERNS 或 WAIVED 时，Story 才能移至 Done。

完成定义

• 已启动运行时，并记录配置／发现检查点
• 已记录快速通道决策检查点
• 已在运行时记录 ln-510 摘要
• 已记录或以确定性方式复用 ln-520 摘要
• 测试验证已达到终止状态或确定性暂停
• 已记录最终判定检查点，包含质量评分和 NFR 结果
• 仅在结果通过时将 Story 移至 Done，或针对 FAIL 创建后续任务
• 已在完成前记录 Stage 3 协调器工件
• 自检已通过，且运行时已完成

阶段 9：元分析

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

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

参考文件

• references/coordinator_runtime_contract.md
• references/story_gate_runtime_contract.md
• references/coordinator_summary_contract.md
• references/minimum_quality_checks.md
• ../ln-510-quality-coordinator/SKILL.md
• ../ln-520-test-planner/SKILL.md

---

版本： 7.0.0 最后更新： 2026-02-09