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/ ルートを対象にします。

プロジェクトの確認： これらの手順は、すでに OpenSpec を使用しているプロジェクトを想定しています。最初に何かを書き込む手順（new change、archive、sync specs、またはアーティファクトファイルの作成）を実行する前に、プロジェクトにルートがあることを確認してください。openspec list --json を実行し（ストアを選択している場合は、そのストアがルートとなるため --store <id> を指定）、root を確認します。ルートオブジェクトがあれば、プロジェクトはセットアップ済みです。"root": null は未セットアップを意味します。ここには openspec/ ディレクトリがなく、openspec new change のような書き込み操作を行うと、副作用としてそのディレクトリが作成されます。このコマンドはゼロ以外の終了コードも返しますが、それは CLI の故障ではなく、答えを示しています。再試行したり回避策を講じたりせず、JSON を確認してください。

status のエラーメッセージが Declared in または Invalid store declaration in で始まり、このプロジェクトの openspec/config.yaml（または config.yml）を示している場合、"root": null はセットアップされていないことを意味しません。このプロジェクトは宣言済みのストアを通じて OpenSpec を使用していますが、このマシンでは解決できません（ストアが登録されていないか、store: 行の形式が不正です）。未初期化と判断して以下の分岐に進んではいけません。書き込みを行う前に停止し、そのエラーの message と fix をユーザーに提示してください。

それ以外の場合、ルートがないときに次に行うことは、このワークフローに至った経緯によって異なります。

• 自動選択： ユーザーが OpenSpec を指定したり、このスキルを指定したり、スラッシュコマンドを実行したりしておらず、自分でこのワークフローを選択した場合です。OpenSpec の使用をやめ、OpenSpec がインストールされていない場合と同様に、通常どおりリクエストに回答してください。セットアップを促したり、OpenSpec のセットアップについて言及したりしないでください。
• 明示的な OpenSpec のリクエスト： ユーザーが OpenSpec またはこのスキルを指定した場合、あるいはスラッシュコマンドを実行した場合です。書き込みを行う前に停止し、どう進めるかを確認してください。このプロジェクトをセットアップする（openspec init）、すでにあるストアを対象にする（--store <id>）、または今回のリクエストでは OpenSpec を使わずに続行する、という選択肢を提示します。回答を待ってください。

どちらの分岐でも、副作用としてルートを作成してはいけません。ユーザーから依頼されるまでは openspec init を実行せず、openspec/ ファイルを手動で作成せず、コマンドによって作成されることも防いでください。

入力： 変更名は任意で指定できます。省略された場合は、会話の文脈から推測できるか確認してください。曖昧な場合や判断できない場合は、利用可能な変更をユーザーに尋ねてください。

手順

1. 変更を選択する

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

   • ユーザーが変更に言及していれば、会話の文脈から推測します
   • アクティブな変更が 1 つだけなら、それを自動選択します
   • 曖昧な場合は、openspec list --json を実行して利用可能な変更を確認し、ユーザーに選択を依頼します

   確認を求める際は、status: "no-tasks" の変更も含め、一覧で返されたすべてのアクティブな変更を提示してください。 各変更のスキーマがわかる場合は、それも含めてください。 タスクが未完了の変更には「（進行中）」と表示してください。

   必ず「使用する変更：」と、その変更を上書きする方法（例：/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 から具体的なファイルパスの配列への対応）、taskTrackingConfigured、およびスキーマの apply.tracks 設定に一致し、読み取り可能だったすべての具体的なファイルから集約した、最上位の tasks と progress が返されます。contextFiles にある利用可能な成果物をすべて読み取ります。

   apply の state と instruction はコンテキストとして扱い、検証の判定結果として扱わないでください。検証中にタスクを実装したり、変更をアーカイブしたりしないでください。

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

   次の 3 つの観点でレポート構成を作成します。

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

   各観点には、CRITICAL、WARNING、SUGGESTION の問題を含めることができます。

   検証は助言を目的としています。skip_specs: true、任意の設計ドキュメント、タスク追跡を行わないスキーマなど、意図的な省略を尊重します。クリーンなレポートを得るために、任意の成果物や意図的に省略された成果物を必須としたり、存在するものとして扱ったりしないでください。Not verified は、このレポートの制約を示すものであり、新たなアーカイブ前提条件ではありません。アーカイブには、独自のチェックとユーザー確認の動作があります。

   スキーマで定義されていないチェックや、ステータスによって意図的にスキップされたと報告されている成果物は、該当なしとしてマークします。読み取り可能な差分仕様に REMOVED または RENAMED の要件が含まれ、ADDED または MODIFIED の要件が含まれない変更の正確性チェックも、該当なしとしてマークします（手順 6 を参照）。これらはスキップされたチェックの件数とアーカイブ準備状況の評価から除外します。Not verified は、該当するチェックの根拠が不足している、または使用できない場合に限って使用します。

   該当するチェックに対してタスクの根拠しかない場合は、タスクの完了のみを検証し、Code Pattern Consistency を含む残りの該当するチェックは、「タスクの根拠のみ利用可能」という理由で未検証としてマークします。

   成果物が読み取れない、または利用可能な要件、シナリオ、設計上の決定が含まれていない場合は、影響を受けるチェックを具体的な理由とともに未検証としてマークします。残りの根拠で裏付けられるチェックは続行しますが、入力の一部しかチェックできていない場合、そのチェックを完全に検証済みとはしません。要件が不足している場合は仕様の網羅状況と要件実装の対応付けに影響します。シナリオが不足している場合はシナリオの網羅状況に影響します。設計上の決定が不足している場合は設計への準拠状況に影響します。

5. 完全性を検証する タスクの完了:

   • taskTrackingConfigured が false の場合、タスクの完了は該当なしとして報告します。空の tasks を証拠の欠落として扱わないでください。
   • それ以外の場合は、トップレベルの tasks フィールドと progress フィールドを使用します。これらは、追跡対象の成果物の ID に関係なく、apply.tracks に一致する読み取り可能なすべての具体的なファイルをすでに集約しています。contextFiles キーから追跡を推測しないでください。
   • unavailableTrackingFiles が空でない場合、タスクの完了を未検証としてマークし、利用できないすべてのパスと理由を含めてください。読み取り可能なタスクの証拠は引き続き使用しますが、部分的な tasks フィールドと progress フィールドから完了を推測しないでください。
   • taskTrackingConfigured が true で tasks が空の場合、タスクの完了を未検証としてマークし、apply の state と instruction から理由を記録してください。合計がゼロでないことだけでは、評価可能なタスク記述が確立されません。
   • progress から完了タスク数と合計タスク数を報告します。
   • progress.remaining が 0 より大きい場合:
     • リストされた各未完了タスクに対して CRITICAL の問題を追加します。残りの数がリストされた未完了タスクを超える場合は、説明のない未完了チェックボックスも報告し、説明を追加して完了することを推奨します。リストされたタスクだけから完了を推測しないでください。
     • 推奨: 「タスクを完了する: 」または「すでに実装済みの場合は完了としてマークする」 仕様カバレッジ：
   • ステータスで仕様アーティファクトが skip_specs: true によりスキップされている場合、またはスキーマに仕様アーティファクトが定義されていない場合（artifactPaths.<id>.outputPath が specs/ 配下にあるアーティファクトがない場合）、仕様に依存するチェックは該当なしとして報告します。
   • それ以外の場合、contextFiles はアーティファクト ID をキーとし、アーティファクト ID はアクティブなスキーマから取得するため、specs などの ID を前提にしてはいけません。仕様アーティファクトは、artifactPaths.<id>.outputPath が specs/ 配下にあるものです。ファイルは contextFiles.<id> から読み込みます。仕様ファイルが存在しないか空の場合は、仕様カバレッジ、要件実装マッピング、シナリオカバレッジを未検証とし、いずれも問題なしとして扱ってはいけません。
   • 仕様ファイルに差分仕様がある場合：
     • すべての要件を抽出します（「### Requirement:」で示されたもの、または ## RENAMED Requirements の下に FROM:／TO: のペアとして記載されたもの）。各要件が属する差分セクション（## ADDED、## MODIFIED、## REMOVED、## RENAMED Requirements）も記録します。チェック対象はセクションによって決まります。
     • ADDED または MODIFIED の各要件について（MODIFIED の場合は、以前の文言ではなく差分内のテキストを確認します）：
       • 要件に関連するキーワードでコードベースを検索します。
       • 実装が存在する可能性を評価します。
     • ADDED または MODIFIED の要件が未実装と思われる場合：
       • CRITICAL の問題を追加します：「Requirement not found: 」
       • 推奨事項：「Implement requirement X: 」
     • REMOVED の各要件について、変更ではその動作の削除が求められているため、チェックを逆にします。
       • REMOVED ブロックには、要件名と **Reason**／**Migration** の注記のみが含まれ、差分には動作自体が記述されていません。検索する前に、差分仕様と同じ capability path を使って、メイン仕様の <planningHome.root>/openspec/specs/<capability-path>/spec.md にあるベースライン要件を読み込みます。REMOVED ブロックを適用する際に OpenSpec が使うルールに従って、完全に一致する正規化済みの名前で照合します。つまり、Requirement: の後の見出しテキストをトリミングし、スペースまたはタブが前にある場合に限り末尾の # の連続を削除して、大文字と小文字を区別して比較します（C# では # を保持します）。似た表現の見出しは一致とはみなしません。名前の変更は RENAMED に属します。動作を特定する根拠は本文とシナリオです。要件名だけを基に検索してはいけません。
       • ファイルにその正確な正規化済みの名前を持つ要件がない場合（たとえば、以前の同期ですでに削除が適用されている場合や、似た名前の ADDED 要件に置き換えられている場合）、計画リポジトリ内の同じファイルの履歴からベースラインを復元します。現在のディレクトリではなく、git -C "<planningHome.root>" log -p -- openspec/specs/<capability-path>/spec.md を使うか、削除を適用したコミットを特定した後で git -C "<planningHome.root>" show <commit>^:./openspec/specs/<capability-path>/spec.md を使います。出力が空でも、パス指定が何にも一致しなかったことを意味する場合があります。ベースラインが存在しないという意味ではありません。git log は一致しないパスに対して成功を返すため、何も表示されないことから結論を出す前にパスを再確認してください。
       • 要件名を言い換えただけで、本文がなくシナリオもないなど、独自の内容を何も追加していないベースラインは、欠落しているベースラインと同様に根拠として使用できません。どちらの場所からも使用可能なベースラインを取得できない場合は、その項目について理由を添えて仕様カバレッジを未検証とし、そこで終了します。検索を行ってはいけません。また、検索していない削除要件を合格として数えてはいけません。
       • その動作についてコードベースを検索します。openspec/ のアーティファクトやドキュメントにある一致、または Migration 注記や ADDED 要件のみを対象とするコード内の一致は、それだけでは根拠になりません。ADDED 要件と共有されている場合も含め、削除対象の動作を提供し続けるコードパスを報告します。
       • 実装が見つからないことが期待される結果ですが、これは検索対象がベースラインの動作であった場合に限ります。REMOVED の要件を「Requirement not found」として報告したり、その実装を推奨したりしてはいけません。
       • その動作がまだ存在する場合：
         • CRITICAL の問題を追加します：「Removed requirement still implemented: 」
         • 推奨事項：「Remove the remaining implementation at :, following the requirement's Migration note if it has one」
     • RENAMED の各エントリ（FROM:／TO:）について、名前は変わりますが動作は維持されるため、変更されていない動作について TO 要件を確認します。
       • FROM 名を見つからないものとして報告してはいけません。また、コードシンボル、識別子、ファイル名の変更を求めてはいけません。
       • TO 名が MODIFIED の下にもある場合、その動作は MODIFIED のテキストに照らしてそこで確認します。この場合、ここでは確認をスキップします。
       • それ以外の場合、差分仕様と同じ capability path を使って、メイン仕様の <planningHome.root>/openspec/specs/<capability-path>/spec.md にあるベースライン要件を読み込みます。FROM 名の要件、またはメイン仕様がすでに同期済みで FROM 名が存在しない場合に限り TO 名の要件を読み込みます。その本文とシナリオが、TO 要件で維持される動作の根拠となります。
       • その動作についてコードベースを検索し、実装が引き続き存在するか評価します。
       • 未実装と思われる場合：
         • CRITICAL の問題を追加します：「Renamed requirement not found: 」
         • 推奨事項：「Restore the behavior of (renamed from ); a rename must not change behavior」
       • ベースライン要件が見つからない、または読み込めない場合は、理由を添えてその項目の仕様カバレッジを未検証とします。確認していない名称変更を合格として数えてはいけません。

6. 正しさを検証する

   差分仕様が読み取り可能で、REMOVED または RENAMED の要件を少なくとも 1 つ含み、ADDED または MODIFIED の要件を含まない場合（変更が要件の削除または名前変更のみの場合）は、Requirement Implementation Mapping と Scenario Coverage を Not applicable と報告します。このような変更の根拠となるのは、Spec Coverage の REMOVED と RENAMED の確認です（ベースラインを利用できる REMOVED および RENAMED の各項目は、そこでベースラインの動作と照合され、そこで「未検証」とすでにマークされている項目は未検証のままです）。したがって、この 2 つの確認を「未検証」とマークしないでください。解析可能な要件がまったくない差分仕様は、削除のみの変更ではなく、使用できない根拠です。この場合、これらの確認を「未検証」とマークしてください。

   Requirement Implementation Mapping:

   • 差分仕様にある各 ADDED または MODIFIED の要件について（REMOVED の項目、および MODIFIED ブロックのない RENAMED の項目は Spec Coverage で確認済みです）：
     • コードベースを検索し、実装の根拠を探します
     • 見つかった場合は、ファイルパスと行範囲を記録します
     • 実装が要件の意図と一致しているか評価します
     • 相違が見つかった場合：
       • WARNING を追加します："Implementation may diverge from spec:
         "
       • 推奨事項："Review : against requirement X"

   Scenario Coverage:

   • 差分仕様の ADDED または MODIFIED の要件に含まれる各シナリオについて（"#### Scenario:" でマークされています）：
     • 条件がコードで処理されているか確認します
     • シナリオを網羅するテストがあるか確認します
     • シナリオが網羅されていないと思われる場合：
       • WARNING を追加します："Scenario not covered: "
       • 推奨事項："Add test or implementation for scenario: "
   • REMOVED の要件に含まれるシナリオはスキップしてください。その動作は削除されることが意図されています。

7. 一貫性を検証する

   Design Adherence:

   • スキーマに設計成果物が定義されていない場合（id が design の成果物がなく、artifactPaths.<id>.outputPath が design.md であるか、design.md で終わる成果物もない場合）は、Design Adherence を「該当なし」と報告します。
   • 設計成果物の contextFiles.<id> ファイルが存在する場合：
     • 重要な決定事項を抽出します（"Decision:"、"Approach:"、"Architecture:" などのセクションを探します）
     • 実装がそれらの決定事項に従っているか確認します
     • 矛盾が見つかった場合：
       • WARNING を追加します："Design decision not followed: "
       • 推奨事項："Update implementation or revise design.md to match reality"
   • それ以外の場合、設計成果物の contextFiles.<id> ファイルが存在しないか空であれば、Design Adherence を「未検証」とマークします。他の補足成果物がある場合は、Code Pattern Consistency も引き続き実施します。タスクのみのケースでは、引き続きタスクの完了確認に限定されます。

   Code Pattern Consistency:

   • 実装の変更を特定できない場合は、Code Pattern Consistency を「未検証」とマークし、根拠が不足していることを説明します。
   • それ以外の場合は、新しいコードがプロジェクトのパターンと一貫しているか確認します
   • ファイル名、ディレクトリー構成、コーディングスタイルを確認します
   • 重大な逸脱が見つかった場合：
     • SUGGESTION を追加します："Code pattern deviation:
       "
     • 推奨事項："Consider following project pattern: "

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

   Summary Scorecard:

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

   各 Status セルには、実施した確認の結果と、スキップした確認それぞれについて Not verified (<reason>) を報告します。ある区分の確認がすべてスキップされた場合は、セルの先頭に Not verified と記載します。スキップした確認を合格として採点しないでください。未検証または部分的に検証された確認はすべて、最終評価ではスキップとして扱います。N には ADDED および MODIFIED の要件のみを数え、REMOVED および RENAMED の要件は別途報告します（例："1 removal confirmed, 1 rename verified"、または "1 removal not verified (baseline unavailable)"）。要件の削除または名前変更のみの変更の場合、Correctness セルには Not applicable (no ADDED or MODIFIED requirements) と記載します。

   Issues by Priority:

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

      • 未完了のタスク
      • 要件の実装漏れ
      • 削除された要件が引き続き実装されている
      • 名前が変更された要件の動作が実装されていない
      • それぞれに具体的で実行可能な推奨事項を記載します

   2. 警告（修正を推奨）：

      • 仕様／設計との相違
      • シナリオのカバー漏れ
      • それぞれに具体的な推奨事項を記載します

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

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

   最終評価：

   • 重大な問題がある場合：「重大な問題が X 件見つかりました。アーカイブ前に修正してください。」チェックをスキップしたものがある場合は、スキップしたチェックとその理由もすべて記載してください。
   • 重大な問題がなく、警告が 1 件以上あり、スキップしたチェックがない場合：「重大な問題はありません。検討すべき警告が Y 件あります（指摘された改善点を反映すればアーカイブ可能です）。」
   • 提案のみで、スキップしたチェックがない場合：「重大な問題も警告もありません。検討すべき提案が Z 件あります（指摘された改善点を反映すればアーカイブ可能です）。」
   • 問題がなく、スキップしたチェックもない場合：「すべてのチェックに合格しました。アーカイブ可能です。」
   • チェックをスキップしており、重大な問題がない場合は、アーカイブ可能としないでください。「実行したチェックでは重大な問題は見つかりませんでした。<チェック>は未検証です：<理由>。」と記載してください。警告が 1 件以上ある場合は、その件数も含めてください。
   • 提案が 1 件以上ある場合は、すべての最終評価に提案の件数を含めてください。

検証の指針

• 完全性：客観的に確認できるチェックリスト項目（チェックボックス、要件一覧）を重視します。
• 正確性：キーワード検索、ファイルパスの分析、妥当な推論を活用してください。完全な確証までは求めません。
• 一貫性：明らかな矛盾を探し、文体を細かく指摘しないでください。
• 誤検知：判断に迷う場合は、「重大」より「警告」、「警告」より「提案」を優先してください。
• 実行可能性：各問題には、該当する場合、ファイル名／行番号を含む具体的な推奨事項を記載してください。

出力形式

以下を含む、明確な Markdown を使用してください。

• 概要スコアカードの表
• 問題を重大／警告／提案ごとにまとめたリスト
• file.ts:123 形式のコード参照
• 具体的で実行可能な推奨事項
• 「確認を検討してください」のような曖昧な提案は避けてください