speckit-converge

ユーザー入力

$ARGUMENTS

空でない場合は、先に進む前にユーザー入力を必ず考慮してください。

実行前チェック

拡張フックを確認する（収束前）：

• プロジェクトルートに .specify/extensions.yml が存在するか確認します。

• 存在する場合はその内容を読み、hooks.before_converge キーの下にあるエントリを探します。

• YAML を解析できない、または無効な場合は、黙ってスキップしてはいけません。.specify/extensions.yml を読み込めなかったこと（パーサーエラーを含む）と、登録されている必須（optional: false）フックも含め、フックが一切確認されていないことをユーザーに伝えてから、通常どおり続行します。

• enabled が明示的に false のフックを除外します。enabled フィールドがないフックは、デフォルトで有効として扱います。

• 残りの各フックについて、condition 式を解釈または評価しようとしてはいけません。

  • フックに condition フィールドがない場合、または null／空の場合は、実行可能なフックとして扱います。
  • フックに空でない condition が定義されている場合は、そのフックをスキップし、条件の評価は HookExecutor の実装に委ねます。

• フックのコマンド名からコマンド呼び出しを構成する際は、ドット（.）をハイフンに置き換えます。たとえば、speckit.git.commit → /speckit-git-commit です。

• 実行可能な各フックについて、optional フラグに応じて次の内容を出力します。

  • 任意のフック（optional: true）：

    ## 拡張フック
    
    **任意の事前フック**：{extension}
    コマンド：`/{command}`
    説明：{description}
    
    プロンプト：{prompt}
    実行するには：`/{command}`
    

  • 必須のフック（optional: false）：

    ## 拡張フック
    
    **自動事前フック**：{extension}
    実行中：`/{command}`
    EXECUTE_COMMAND: {command}
    
    続行して目標に進む前に、フックコマンドの結果を待ってください。
    

    上記のブロックを出力した後、必ず実際にフックを呼び出し、完了するまで待ってから続行してください。このエージェント／セッションで自身がコマンドを実行する場合と同じ方法で実行します（呼び出し方法は、表示された {command} ID と異なる場合があります。たとえば、スキルモードのエージェントでは /skill:speckit-... または $speckit-... で実行します）。ブロックを出力しただけでは、フックを実行したことにはなりません。

• フックが登録されていない場合、または .specify/extensions.yml が存在しない場合は、何も表示せずにスキップします。

目標

機能の仕様、計画、タスクが求める内容と、現在コードベースで実装されている内容のギャップを埋めます。spec.md、plan.md、tasks.md を唯一の意図の根拠として（憲章は制約として適用）、コードの現状を評価し、未達、未完了、または部分的にしか満たされていない要件、受け入れ基準、計画上の決定事項、既存タスクを特定します。そして、残作業をそれぞれ追跡可能な新しいタスクとして tasks.md の末尾に追加し、/speckit-implement で完了できるようにします。このコマンドは、現在の tasks.md に対して /speckit-implement が実行され、さらに /speckit-tasks によって完全な tasks.md が作成された後にのみ実行しなければなりません。

これは差分ツールではなく、変更を追跡するものでもありません。git、ブランチ比較、履歴は使用せず、機能の成果物に照らしてコードの現状を評価します。

運用上の制約

追記のみ、書き換え禁止：このコマンドによる唯一の書き込みは、tasks.md に新しい ## Phase N: Convergence セクションを追記することです。以下を行ってはなりません。

• spec.md または plan.md を一切変更しない。
• 既存のタスク（以前の Convergence フェーズのタスクを含む）を書き換えたり、番号を振り直したり、順序を変更したり、削除したりしない。
• アプリケーションコードを変更、作成、削除しない。追記したタスクの完了は /speckit-implement の役割です。

コードベースがすでにすべての条件を満たしている場合、コマンドは tasks.md を バイト単位で変更せず（空の Convergence ヘッダーも追加せず）、問題がない結果を報告しなければなりません。

憲章の権威：プロジェクト憲章（.specify/memory/constitution.md）は 交渉の余地がありません。MUST 原則に違反するコードは最も重大度の高い指摘となり、対応する修正タスクが作成されます。憲章が未記入のテンプレートの場合は、失敗せずに憲章のチェックをスキップしてください。

実行手順

1. Convergence コンテキストを初期化する

リポジトリのルートから .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks を一度実行し、JSON を解析して FEATURE_DIR と AVAILABLE_DOCS を取得します。絶対パスを導出します。

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md
• CONSTITUTION = .specify/memory/constitution.md（存在する場合） spec.md、plan.md、または tasks.md がない場合は、実行すべき前提コマンド（spec がない場合は /speckit-specify、plan がない場合は /speckit-plan、tasks がない場合は /speckit-tasks）を明記した、明確で実行可能なメッセージを表示して停止してください。部分的な出力を生成してはなりません。 「I'm Groot」のように引数にシングルクォートが含まれる場合は、エスケープ構文を使用してください。例：'I'''m Groot'（または可能であれば、"I'm Groot" のようにダブルクォートで囲みます）。

2. 成果物を読み込む（段階的な開示）

各成果物から必要最小限のコンテキストだけを読み込みます。

spec.md から：

• 機能要件（FR-###）
• 成功基準（SC-###）— 実装可能な作業が必要な項目のみを含め、リリース後の成果指標やビジネス KPI は除外します。
• ユーザーストーリーとその受け入れシナリオ
• エッジケース（存在する場合）

plan.md から：

• アーキテクチャ／スタックの選択と技術的決定
• データモデルへの参照
• フェーズと名前付きのタッチポイント（plan で作成または編集するとされているファイル／コンポーネント）
• 技術的制約

tasks.md から：

• タスク ID（次の ID と次のフェーズ番号を算出するため）
• 説明、フェーズ分け、参照されているファイルパス

憲章から（未記入のテンプレートではない場合）：

• 原則名と MUST／SHOULD の規範的な記述

3. 要件インベントリを作成する

内部モデルを作成します（成果物の生データをそのまま出力しないでください）。

• 要件インベントリ：各 FR-###／SC-###／ユーザーストーリーの受け入れシナリオ（例：US1/AC2）に安定したキーを 1 つ割り当て、実装可能な義務を課す plan の決定事項と憲章の原則も含めます。
• コードスコープマップ：plan.md と tasks.md に記載されたファイルパスに加え、各要件の概念をキーワード検索し、評価対象となるソースファイルとコンポーネントの集合を導き出します。評価範囲はこれらに限定し、成果物で定義されていない範囲まで推測してはなりません。

4. コードベースを評価し、調査結果を分類する

チェックボックスの状態や Convergence フェーズに関係なく、インテントインベントリに含まれるすべての既存タスクを対象にします。完了したという主張は証拠にはなりません。仕様、計画、タスク、憲章に照らして現在の動作を検証してください。修正タスクの連鎖については、置き換えられた実装の詳細ではなく、最終的な動作を評価します。未達の義務と、明示された意図に反する、意図を超える、または意図の範囲外にある実装の両方を確認してください。

インテントインベントリの各項目について、対象範囲内の現在のコードを調査し、ギャップがある場合にのみ Finding を作成します。すべての調査結果をギャップタイプで分類してください。

• missing：必要な作業がコードにまったく存在しません。
• partial：作業は存在しますが、要件／受け入れ基準／計画上の決定をまだ完全には満たしていません。
• contradicts：コードが明示された意図または憲章の MUST 原則に反する動作をしています。
• unrequested：仕様、計画、タスクで求められていない作業がコードに含まれています（認識のために提示します。converge はコードを削除せず、レビューして正当性を確認するか、削除するタスクを追加するだけです）。

各 Finding には、安定した ID、参照元を示す source-ref、gap-type、重大度、証拠（確認したファイル／領域）を含む、人が読める簡潔な説明を記録します。

エッジケース：

• コードがほとんどない、またはまったくない場合：失敗とせず、仕様で定められた範囲全体を未完了の missing 作業として扱います。
• 残作業がない場合：調査結果をゼロ件とし、ステップ 7 の収束済み分岐に進みます。

5. 重大度を割り当てる

• CRITICAL：憲章の MUST 原則に違反している場合、または P1 ユーザーストーリーの基本機能を妨げる missing／contradicts ギャップ。
• HIGH：中核的な機能要件または受け入れ基準に関する missing または partial ギャップ。
• MEDIUM：副次的な要件に関する partial ギャップ、または正当性が不明確な unrequested の追加。
• LOW：軽微な partial ギャップ、仕上げ、またはリスクの低い unrequested の追加。

6. セッション内の調査結果サマリーを提示する

何かを追加する前に、重大度別に簡潔なサマリーを出力します（まだファイルには書き込みません）。

Convergence Findings

ID	Gap Type	Severity	Source	Evidence	Remaining Work
F1	missing	HIGH	FR-008	例：tasks.md への書き込み時に、path/to/module.py で追記専用のガードが検出されない	追記専用の強制を追加する

サマリー指標：

• 確認した要件／受け入れ基準
• 確認した計画上の決定
• 確認した憲章の原則（または「スキップ — テンプレート」）
• ギャップタイプ別の調査結果数（missing / partial / contradicts / unrequested）
• 重大度別の調査結果数

7. 収束タスクを追加する（または収束済みと報告する）

対応可能な指摘事項が1件以上ある場合（tasks_appended の結果）：

追加規約に従って、tasks.md の末尾に追加します。

1. 既存のすべてのタスク ID を確認し、最大値を M とします。次のフェーズ番号 N を決定します （既存のフェーズ番号の最大値 + 1）。

2. 新しいセクション見出し ## Phase N: Convergence を1つ記述します。

3. 対応可能な指摘事項ごとにチェックリスト項目を1つ出力し、CRITICAL/HIGH を先に並べ、ゼロ埋め ID T{M+1:03d}, T{M+2:03d}, … を割り当てます。

   - [ ] T042 <imperative description> per <source-ref> (<gap-type>)
   

   <source-ref> は、タスクの発生元を示します。例：FR-003、SC-002、 US1/AC2、plan: storage decision、Constitution II。

   <gap-type> は missing、partial、contradicts、unrequested のいずれかです。

   Constitution 違反に関するタスクは、必ず最初に出力し、CRITICAL として記述します。

4. 既存の ID を再利用したり、振り直したりしないでください。以前の Convergence フェーズがある場合は、古いフェーズに手を加えず、その下に番号を付けた新しいフェーズを追加します。

対応可能な指摘事項がない場合（converged の結果）：

• tasks.md は一切変更しないでください。空のフェーズ見出しも追加しません。
• **「✅ 収束済み — 実装は仕様、計画、タスクを満たしています。」**と報告します。
• 確認した内容の概要件数も含めます。

8. 次のアクションを提示する（引き継ぎ）

• tasks_appended の場合：どのフェーズに何件のタスクを追加したかを伝え、完了のために /speckit-implement の実行を推奨します。続けて収束チェックを実行すると、残りの項目が減るか、なくなることも伝えます。
• converged の場合：レビューに進むか、PR を作成することを推奨します。この機能の指定された範囲について、追加の実装パスは不要です。

9. 拡張フックを確認する

結果を出力した後、プロジェクトルートに .specify/extensions.yml が存在するか確認します。

• 存在する場合は読み込み、hooks.after_converge キーの下にあるエントリーを確認します。

• YAML を解析できない、または無効な場合は、黙ってスキップしないでください。.specify/extensions.yml を読み込めなかったこと（パーサーエラーを含む）と、そこに登録されている必須（optional: false）フックも含め、フックを確認していないことをユーザーに伝えてから、通常どおり続行します。

• enabled が明示的に false のフックは除外します。enabled フィールドがないフックは、デフォルトで有効として扱います。

• 残りの各フックについて、condition 式を解釈または評価しようとしないでください。

  • フックに condition フィールドがない場合、またはその値が null／空の場合、実行可能なフックとして扱います。
  • フックに空でない condition が定義されている場合は、そのフックをスキップし、条件の評価は HookExecutor 実装に委ねます。

• フックを一覧表示する前に、収束の結果（converged または tasks_appended）をセッション内で報告し、ユーザーが任意の後続コマンドを実行するか判断できるようにします。

• フックのコマンド名からコマンド呼び出しを作成する際は、ピリオド（.）をハイフン（-）に置き換えます。例：speckit.git.commit → /speckit-git-commit。

• 実行可能な各フックについて、optional フラグに基づいて以下を出力します。

  • 任意のフック（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • 必須フック（optional: false）：

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    上記のブロックを出力した後、続行する前に必ずフックを実際に呼び出し、完了を待ちます。このエージェント／セッションでコマンドを自分で実行する場合と同じ方法で実行してください（呼び出し方は、上記に表示した {command} の ID と異なる場合があります。例：skills モードのエージェントでは /skill:speckit-... または $speckit-... として実行します）。ブロックを出力するだけでは、フックを実行したことにはなりません。

• フックが登録されていない場合、または .specify/extensions.yml が存在しない場合は、何もせずにスキップします。