openspec-verify-change

実装が変更アーティファクト（仕様、タスク、設計）に一致していることを検証します。

**ストアの選択：**ユーザーがストア（このマシンに登録されている独立した OpenSpec リポジトリ）を指定した場合、または作業対象がストア内にある場合は、openspec store list --jsonを実行して登録済みのストア ID を確認し、仕様や変更を読み書きするコマンド（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）に--store <id>を渡します。選択後は、以降のワークフロー全体で--store <id>を指定し続けてください。以下のコマンド例でストアが指定されていない場合は、すべて省略形です。実行する前にフラグを追加してください。たとえば、以下に示すストア指定なしの形式ではなく、openspec status --change "<name>" --json --store "<id>"を実行します。その他のコマンドでは、このフラグは使用しません。コマンドが出力するヒントにはすでにフラグが含まれています。後続のコマンドでも指定したままにしてください。ストアが選択されていない場合、コマンドは最も近いローカルのopenspec/ルートを対象にします。

入力：変更名は任意で指定できます。省略された場合は、会話の文脈から推測できるか確認します。曖昧な場合や複数の候補がある場合は、利用可能な変更をユーザーに確認しなければなりません。

手順

1. 変更を選択する

   名前が指定されている場合は、それを使用します。指定されていない場合：

   • 会話の中でユーザーが変更について言及していれば、そこから推測します
   • アクティブな変更が1つだけの場合は、自動選択します
   • 複数の候補がある場合は、openspec list --jsonを実行して利用可能な変更を取得し、ユーザーに選択を依頼します

   ユーザーに確認するときは、実装タスクがある変更（tasks アーティファクトが存在するもの）を表示します。 各変更で使用されているスキーマがあれば、それも含めます。 タスクが未完了の変更には「（進行中）」と表示します。

   常に「Using change: 」とアナウンスし、変更方法（例：/openspec-verify-change <other>）も示します。

2. スキーマを把握するためにステータスを確認する

   openspec status --change "<name>" --json
   

   JSON を解析し、以下を把握します：

   • schemaName：使用されているワークフロー（例：「spec-driven」）
   • planningHome、changeRoot、artifactPaths、actionContext：パスとスコープのコンテキスト
   • この変更で存在するアーティファクト

3. 計画のコンテキストを取得し、アーティファクトを読み込む

   openspec instructions apply --change "<name>" --json
   

   これにより、変更ディレクトリとcontextFiles（アーティファクト ID -> 具体的なファイルパスの配列）が返されます。contextFiles内にあるすべてのアーティファクトを読み込みます。

4. 検証レポートの構造を初期化する

   以下の3つの観点でレポート構造を作成します：

   • 完全性：タスクと仕様のカバレッジを追跡します
   • 正確性：要件の実装とシナリオのカバレッジを追跡します
   • 一貫性：設計への準拠とパターンの一貫性を追跡します

   各観点には、CRITICAL、WARNING、SUGGESTION の問題が含まれる場合があります。

5. 完全性を検証する

   タスクの完了状況：

   • contextFiles.tasksが存在する場合は、その中のすべてのファイルパスを読み込みます
   • チェックボックスを解析します：- [ ]（未完了）と- [x]（完了）
   • 完了タスク数と全タスク数を数えます
   • 未完了のタスクがある場合：
     • 未完了のタスクごとに CRITICAL の問題を追加します
     • 推奨事項：「タスクを完了してください：」または「すでに実装済みの場合は完了としてマークしてください」

   仕様のカバレッジ：

   • contextFiles.specsに差分仕様がある場合：
     • すべての要件（「### Requirement:」で示されるもの）を抽出します
     • 各要件について：
       • 要件に関連するキーワードでコードベースを検索します
       • 実装が存在する可能性を評価します
     • 要件が未実装と思われる場合：
       • CRITICAL の問題を追加します：「要件が見つかりません：」
       • 推奨事項：「要件 X を実装してください：」

6. 正確性を検証する

   要件と実装の対応付け：

   • 差分仕様の各要件について：
     • コードベースで実装の根拠を検索します
     • 見つかった場合は、ファイルパスと行範囲を記録します
     • 実装が要件の意図に一致しているか評価します
     • 相違が検出された場合：
       • WARNING を追加します：「実装が仕様と異なる可能性があります：
         」
       • 推奨事項：「:を要件 X と照らし合わせて確認してください」 シナリオの網羅性：
   • delta の仕様にある各シナリオ（「#### Scenario:」で示されるもの）について：
     • 条件がコードで処理されているか確認します
     • シナリオを網羅するテストが存在するか確認します
     • シナリオが網羅されていないように見える場合：
       • WARNING を追加します：「シナリオが網羅されていません：」
       • 推奨事項：「シナリオのテストまたは実装を追加してください：」

7. 整合性を検証する

   設計への準拠：

   • contextFiles.design が存在する場合：
     • 重要な決定事項を抽出します（「Decision:」「Approach:」「Architecture:」などのセクションを確認します）
     • 実装がそれらの決定事項に従っているか検証します
     • 矛盾が検出された場合：
       • WARNING を追加します：「設計上の決定事項に従っていません：」
       • 推奨事項：「実装を更新するか、実態に合わせて design.md を修正してください」
   • design.md がない場合：設計への準拠チェックをスキップし、「検証対象の design.md がありません」と記載します

   コードパターンの一貫性：

   • 新しいコードがプロジェクトのパターンと一貫しているか確認します
   • ファイル名、ディレクトリ構造、コーディングスタイルを確認します
   • 重大な逸脱が見つかった場合：
     • SUGGESTION を追加します：「コードパターンからの逸脱：
       」
     • 推奨事項：「プロジェクトのパターンに従うことを検討してください：」

8. 検証レポートを作成する

   概要スコアカード：

   ## Verification Report: <change-name>
   
   ### Summary
   | Dimension    | Status           |
   |--------------|------------------|
   | Completeness | X/Y tasks, N reqs|
   | Correctness  | M/N reqs covered |
   | Coherence    | Followed/Issues  |
   

   優先度別の問題：

   1. CRITICAL（アーカイブ前に必ず修正）：

      • 未完了のタスク
      • 要件の実装漏れ
      • それぞれに具体的で実行可能な推奨事項を記載します

   2. WARNING（修正を推奨）：

      • 仕様／設計との不一致
      • シナリオの網羅漏れ
      • それぞれに具体的な推奨事項を記載します

   3. SUGGESTION（修正すると望ましい）：

      • パターンの不整合
      • 軽微な改善点
      • それぞれに具体的な推奨事項を記載します

   最終評価：

   • CRITICAL の問題がある場合：「重大な問題が X 件見つかりました。アーカイブ前に修正してください。」
   • WARNING のみの場合：「重大な問題はありません。検討すべき警告が Y 件あります（改善点を反映したうえで）アーカイブできます。」
   • 問題がない場合：「すべてのチェックに合格しました。アーカイブできます。」

検証のヒューリスティクス

• 完全性：客観的なチェックリスト項目（チェックボックス、要件一覧）に重点を置きます
• 正確性：キーワード検索、ファイルパスの分析、妥当な推論を使用し、完全な確実性は求めません
• 整合性：明らかな矛盾を探し、スタイルの細部にこだわりすぎないようにします
• 誤検出：確信が持てない場合は、WARNING より SUGGESTION を、CRITICAL より WARNING を優先します
• 実行可能性：すべての問題に、該当する場合はファイル／行への参照を含む、具体的な推奨事項を付けます

段階的な検証

• tasks.md のみが存在する場合：タスクの完了のみを検証し、仕様／設計のチェックはスキップします
• タスクと仕様が存在する場合：完全性と正確性を検証し、設計のチェックはスキップします
• すべての成果物がそろっている場合：3 つの観点すべてを検証します
• どのチェックをスキップしたか、またその理由を必ず記載します

出力形式

次の要素を含む、明確な Markdown を使用します：

• 概要スコアカードの表
• 問題をグループ分けしたリスト（CRITICAL／WARNING／SUGGESTION）
• 次の形式によるコード参照：file.ts:123
• 具体的で実行可能な推奨事項
• 「確認を検討してください」のような曖昧な提案は避けます