ln-500-story-quality-gate

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

タイプ： L2 コーディネーター カテゴリー： 5XX 品質

ストーリー品質ゲート

ランタイムに基づくゲートコーディネーターです。ファストトラックのルーティング、品質／テストの要約、最終的なストーリーの判定、ブランチの最終処理を担当します。

入力

入力	必須	ソース	説明
storyId	はい	args, git branch, kanban, user	処理するストーリー

解決方法： ストーリー解決チェーン。
ステータスフィルター： レビュー待ち

目的と範囲

• ln-510-quality-coordinator を呼び出す
• 必要に応じて ln-520-test-planner を呼び出す
• テストタスクの準備完了を確実に待つ
• ゲートの判定を計算する：PASS | CONCERNS | FAIL | WAIVED
• 合格した場合のみストーリーを 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	すべてのチェックに合格	ストーリーを Done に移動
CONCERNS	軽微な問題があるが、リスクを受け入れる	コメントを付けてストーリーを Done に移動
FAIL	ブロッキング問題が見つかった	フォローアップタスクを作成。ストーリーは Done に移動しない
WAIVED	ユーザーが承認した例外	免除の証拠を添えてストーリーを Done に移動

ワークフロー

フェーズ 0：設定

1. storyId と task_provider を解決します。
2. .hex-skills/runtime-artifacts/runs/*/story-quality/{storyId}.json に過去のステージ 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（null または読み込んだ rework_hint）
   • cycle_number
4. ランタイムを開始し、PHASE_0_CONFIG をチェックポイントとして記録します。

フェーズ 1：検出

1. ストーリーのメタデータと子タスクのメタデータを読み込みます。
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 の場合にのみ、実行を完了します。

ワーカーの呼び出し（必須）

ホストスキルの呼び出し： 委任には Skill(skill: "...", args: "...") が必須です。

• Claude：Skill ツールを上記のとおり正確に呼び出します。
• Codex：Skill ツールがない場合は、利用可能なスキルから指定されたスキルを見つけ、その SKILL.md を読み込み、args を $ARGUMENTS として扱って、そのスキルのワークフローを実行し、その結果またはアーティファクトを持ってここに戻ります。
• ワーカーロジックをインラインで実行したり、対象のスキルを実行せずにワーカーを完了扱いにしたりしないでください。

フェーズ	ワーカー	目的
3	ln-510-quality-coordinator	コード品質、エージェントレビュー、回帰、ログ分析
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 コーディネーターのアーティファクトであり、ステージの自由記述出力ではありません。
• ストーリーを Done に移せるのは、PASS、CONCERNS、または WAIVED の場合のみです。

完了の定義

• 実行時状態が開始され、設定／検出のチェックポイントが記録されている
• ファストトラックの判断がチェックポイントに記録されている
• ln-510 の要約が実行時状態に記録されている
• ln-520 の要約が記録されている、または決定論的に再利用されている
• テスト検証が最終状態または決定論的一時停止に到達している
• 品質スコアと NFR の結果を含む最終判定がチェックポイントに記録されている
• 合格結果の場合のみストーリーが 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