aep-validate

検証

AEP ワークフローで作成された任意の成果物に対して、生成／評価パターンを実行します。生成エージェントは成果物を使用しようとし（ドライラン）、評価エージェントは実際の状況（コードベース、制約、後続プロトコル）と照らし合わせて確認し、その結果をまとめて成果物自体に修正を適用します。

基本原則： 成果物を作成したエージェントが、それを誠実に評価することはできません。エージェントは自分の仕事を称賛します。生成と評価を分離することで、この問題を解決します。役割分離の契約、採点フレームワーク、エージェントのプロンプトテンプレート、評価プロトコル、指摘事項の形式は /aep-gen-eval のリファレンスに定められています。基礎となる仕組みについてはそちらを参照してください。このスキルでは、そのパターンをプロダクト成果物に適用します。

このスキルの位置付け：

/aep-envision → /aep-map → /aep-model (UI-facing) → /aep-validate → /aep-dispatch → /aep-design → /aep-launch → /aep-build → /aep-wrap
                    ▲ you are here

Also usable after any phase:
  /aep-envision → /aep-validate   (validate product context)
  /aep-map      → /aep-validate   (validate architecture + stories)
  /aep-design   → /aep-validate   (validate specs before launch)
  /aep-build    → /aep-validate   (already built into Phase 5 — use that instead)

セッション： メイン。自律型または対話型 入力： 任意の AEP 成果物（分割モードでは product/index.yaml と product-context.yaml、v1 モードでは product-context.yaml のみ、または OpenSpec 変更、設計ドキュメント、コード） 出力： 問題を修正した同じ成果物。検証レポートを変更履歴に追記します。

---

開始前

検証対象を特定します。

ls product-context.yaml 2>/dev/null   # product context
ls openspec/changes/ 2>/dev/null      # OpenSpec changes
ls .dev-workflow/ 2>/dev/null          # design artifacts

ユーザーが対象を指定した場合は、それを検証します。指定がない場合、上記のプローブで該当するものがちょうど 1 つなら、その成果物を検証します。複数ある場合は、推測せずにどれを検証するか尋ねます。事後条件： エージェントを起動する前に、成果物（具体的なパス）とそのモード（A/B/C/D）が確定していること。

プロダクトコンテキストの場合は、references/file-resolution.md のプローブを使って、分割モードか v1 モードかを判定します（モードの意味に関する基準はここに定められています）。分割モードでは、両方のファイルを検証し、ファイル間の整合性を確認します。v1 モードでは、product-context.yaml のみを検証します。

---

ステップ 0：整合性の事前チェック（機械的・ブロッキング）

エージェントを起動する前に、決定論的なチェックを実行します。低コストで、判断を必要とせず、制御ファイルと作業記録の整合性が失われた場合に発生する種類の不具合を検出します。

node scripts/coherence.mjs --context product-context.yaml

ブロッキング指摘がある場合は、ゼロ以外の終了コードで終了し、それぞれの修正方法を出力します。

指摘事項	ブロックする理由
not_started ゲートの配下に完了済みのストーリーがある	ゲートが作業内容を正しく表しておらず、後続の利用者がすべて誤って読み取るため
ゲートのステータスが定義済みの値の範囲外である	制御ファイルの記述が、内容より先に乖離するため
集計値と記録が一致しない	記録がゼロでないのに合計がゼロであれば、合計についての記述が矛盾するため
ストーリーで使われているが、宣言されていないモジュールがある	アーキテクチャに関するすべての利用者から、その作業が見えなくなるため
スキーマで定義されていないフィールドがある	実際の意味を持つ一方で、フレームワークのどの利用者も読み取れないため

続行する前にブロッキング指摘を修正してください。エージェントは、内容に矛盾のある成果物を評価できません。

導出方法は references/drift-facts.md に定められています。scripts/coherence.mjs は、その実行可能な部分であり、/aep-human-alignment と共有されているため、両者に乖離が生じません。2 行目の「定義済みの値の範囲」は references/aep-vocabulary.schema.json を指しており、チェッカーは実行時にこれを読み込みます。ゲートの状態はコーパス全体で一度だけ宣言され、scripts/json-schema.mjs はその裏で共有されるバリデーターです。

---

ステップ 1：検証モードを決定する

このスキルは、成果物の種類に応じて 4 つのモードのいずれかで動作します。各モードでは、起動するエージェントとその確認内容を設定します。モード A（プロダクトコンテキスト）については以下で詳しく説明します。 モード B（設計）、モード C（コード）、モード D（ドキュメント）については、エージェントの役割、Phase-5 のコード分岐、エージェント数のカスタマイズについて references/modes.md を参照してください。

モード A：プロダクトコンテキストの検証

実行タイミング： /aep-envision または /aep-map の後 — product-context.yaml（分割モードの場合は product/index.yaml も）を検証します

分割モードでのファイル間チェック：

• stories[].layer の値が product/index.yaml の product.layers[] に存在する必要があります
• stories[].activity の値が product/index.yaml の product.activities[] に存在する必要があります
• calibration.plan[].dimensions[] が product/index.yaml の product.quality_dimensions[] を参照している必要があります
• 分割モードが有効な場合、product-context.yaml に opportunity セクションまたは product セクションが存在してはなりません
• product/index.yaml に personas、capabilities、product セクションが必要です
• object-model が宣言済みの品質ディメンションである場合：UI に表示されるすべてのケイパビリティに product/maps/<capability>/object-map.yaml が存在する必要があります。各 stories[].object_model_refs エントリが既存のオブジェクトマップのパスとオブジェクト ID を指している必要があります。また、オブジェクト名が architecture.domain_model および docs/glossary.md と一致している必要があります

モード A では、プロダクト設計の品質を先に、技術的な正確性を後に検証する 2 つのパスを実行します。

パス 1：製品デザインの評価（「適切なものを作っていますか？」）

エージェント： 製品デザイン評価者 + ビジョン整合性チェッカー

エージェント	役割	チェック項目
製品デザイン評価者	ユーザーストーリーマッピングの原則に基づくレビュー	ウォーキングスケルトンの妥当性、レイヤーの順序、INVEST 準拠、依存関係グラフの品質、アクティビティの網羅性、ナラティブの一貫性
ビジョン整合性チェッカー	ストーリーを機会概要に紐付ける	すべてのストーリーが明示されたユーザーニーズに対応していること、スコープクリープがないこと、JTBD の網羅性

/aep-gen-eval の agent-contracts.md にある製品デザイン評価者のプロンプトと、/aep-gen-eval の scoring-framework.md にあるストーリーマッピングの評価項目（ウォーキングスケルトンの妥当性、レイヤーの順序、ビジョンとの整合性、INVEST 準拠）を使用してください。

パス 1 の重大な不合格条件：

• ウォーキングスケルトンの妥当性 < 3 — レイヤー 0 が十分に最小化されていません
• ビジョンとの整合性 < 3 — ストーリーが製品ビジョンから逸脱しています
• INVEST 準拠 < 3 — ストーリーが自律型エージェントにとって実行可能ではありません

パス 1 のアクティビティチェック（product.activities が存在する場合）：

• アクティビティの網羅性： layer_introduced: 0 の各アクティビティに、少なくとも 1 つのレイヤー 0 のストーリーがあること。ストーリーのないアクティビティは、ウォーキングスケルトンの欠落箇所です。
• アクティビティの一貫性： activity が null でないすべてのストーリーが、product.activities にある有効なアクティビティ ID を参照していること。
• ナラティブの一貫性： アクティビティを order の昇順に左から右へ読み、ユーザーの一貫したナラティブを形成していること。「ユーザーが［アクティビティ 1］を行い、次に［アクティビティ 2］を行い、その後……」という流れになっていない場合は、バックボーンを再構成する必要があります。
• インフラストラクチャ比率： レイヤー 0 のストーリーの 60% 超で activity が null の場合、分解が技術寄りすぎる可能性があります。ユーザーが実行できることを中心にストーリーを捉え直してください。

パス 1 のオブジェクトマップチェック（product/maps/*/object-map.yaml が 1 つでも存在する場合）：

• CTA の網羅性： 各 UI ストーリーの動詞が、その機能のオブジェクトマップの coverage にあるオブジェクトの CTA に対応していること。カバーされていない UI ストーリーは、オブジェクトの欠落または隠れたタスクフローを示します。
• オブジェクトのホーム： primary_objects にある各オブジェクトに、screens[] のエントリー（collection または detail）が少なくとも 1 つあること。ホーム画面のない主要オブジェクトには到達できません。
• アンカーの存在： 各機能のオブジェクトマップで navigation.anchor_object が宣言されていること。
• タスクフローの根拠： mode: task_oriented の各 interaction_modes エントリーに、空でない reason があること（デフォルトはオブジェクト優先です。これから外れる場合は根拠が必要です）。
• 承認状態： 機能のオブジェクトマップが status: draft または stale の間は、UI に関わるストーリーをディスパッチ可能な状態にしないでください。先に approved にする必要があります（/aep-model を実行してください）。
• 参照の解決： 各 stories[].object_model_refs エントリー（<path>#<object-id>）が解決できること。パスが存在し、<object-id> がそのマップの primary_objects／supporting_objects と object-model.yaml の objects[] に含まれていること。
• 名詞の網羅性： product.activities から抽出した各名詞がオブジェクトに対応しているか、実装専用であることが正当化されていること。

パス 2：技術検証（「正しく構築できますか？」）

エージェント： Generator + Evaluator + Protocol Checker

エージェント	役割	検証内容
Generator	各ストーリー／レイヤーをドライランする	各ストーリーを実装できるか。不足している詳細、曖昧な基準、依存関係の欠落
Evaluator	設計とコードベースを比較する	パッケージのバージョン、インポートパス、既存のパターン、ファイルの有無、API の互換性
Protocol Checker	下流との互換性を検証する	ディスパッチに必要なフィールド、DAG の妥当性、スコアリングの互換性、ファイル競合の検出

2 パスにする理由： パス 1 ではプロダクト設計の問題（誤ったストーリー、不適切なレイヤリング、ビジョンからの逸脱）を検出し、パス 2 では技術的な問題（フィールドの不足、参照の破損、コードベースとの不整合）を検出します。自律型エージェントにディスパッチする前に両方を実行します。自律型エージェントは、与えられた内容をそのまま構築するためです。

---

ステップ 2：検証コンテキストを組み立てる

各エージェント向けに、焦点を絞ったコンテキストパッケージを準備します。範囲によって評価の品質が決まります。汎用的な Generator と Evaluator のコンテキストのレシピ（含める内容、除外する内容）は、/aep-gen-eval の agent-contracts.md（「Context Assembly Rules」）に規定されています。

Protocol Checker のコンテキスト（Mode A のみ）： 成果物のストーリーセクション、満たす必要がある下流プロトコルの仕様、トポロジーとレイヤーゲートの定義を渡します。下流プロトコルの要件（ディスパッチストーリーのフィールド、スコアリング式、DAG のルール、設計／構築の引き継ぎ契約）は、references/protocol-specs.md に記載されています。

---

ステップ 3：エージェントを起動する

すべてのエージェントを並行して起動します。各エージェントは独立して作業し、互いの出力は参照しません。/aep-gen-eval の agent-contracts.md にあるプロンプトテンプレートを使用します。Generator（Artifact Validation）、Evaluator（Codebase Verification）、Protocol Checker、そして Mode A のパス 1 では Product Design Evaluator も使用します。事後条件： 起動したエージェントごとに 1 件の検出事項レポートが返されていること。

---

ステップ 4：検出事項を統合する

すべてのエージェントからの応答を受け取ったら、検出事項を単一の対応リストに統合します。複数のエージェントが異なる観点から同じ問題を見つけた場合は、根拠をまとめて 1 件の検出事項に統合します。

重大度で分類する

カテゴリー	説明	対応
ブロッキング	下流の利用者が作業できなくなる問題	直ちに修正
重要	摩擦、混乱、または手戻りの原因となる問題	先に進む前に修正
軽微	表面的な問題、任意フィールドの不足、ドキュメントの欠落	記録し、容易に修正できる場合は修正

ユーザーに提示する

修正を適用する前に、件数とともに統合した検出事項を提示します。ユーザーが優先順位を変更したり、検出事項を却下したりする場合があります。

Validation complete: {N} blocking, {M} important, {K} minor issues found.

Blocking:
  1. [issue] — found by Generator + Evaluator
  2. [issue] — found by Protocol Checker

Important:
  3. [issue] — found by Generator
  ...

事後条件： 件数を示した重複のない検出事項のリストがユーザーに提示されていること。

---

ステップ 5：修正を適用する

成果物の現在のディスク上の状態（キャッシュされたコピーではありません）を読み込み、ブロッキングと重要のすべての指摘を修正します。軽微な指摘は変更履歴に記録し、簡単に修正できる場合は修正します。ブロッキングの指摘が残っている限り、成果物は検証済みではありません。

修正のルール：

• 検証対象の成果物のみを変更します。新しいファイルの作成、ほかの成果物の編集、コードの実装は行いません。
• 成果物に既存の構造と規約を維持します。
• 修正にエージェントが決定できない判断（アーキテクチャ上の選択、ビジネス上の優先順位）が必要な場合は、推測で黙って決めず、デフォルトの前提を添えて open_question として記録します。
• 製品コンテキストのスキーマに従い、検証内容と修正したブロッキング／重要／軽微な指摘の件数を記録した変更履歴エントリー（date、author: aep-validate、summary）を追加します。

成果物が product-context.yaml の場合は、コミット前に引き続きパース可能であることを確認します。references/yaml-guardrails.md に記載された検証コマンドを実行してください。事後条件： npx js-yaml product-context.yaml が終了コード 0 で終了すること。

---

ステップ 6：コミット

# Resolve $BASE (integration branch) per /aep-git-ref "Integration Branch".
git pull --ff-only origin "$BASE"
git add <validated-files>
git commit -m "fix: validate {artifact-name} — {N} issues found and fixed"
git push origin "$BASE"

事後条件： 修正がコミットされ、$BASE にプッシュされていること。

---

検証の観点

エージェントは評価時に、モード固有の観点（完全性、一貫性、セキュリティ、実現可能性、正確性など）を重視します。モードごとの観点をまとめた表と、5 項目のコードスコアリングフレームワーク全体への参照先は、references/validation-dimensions.md にあります。

---

このスキルを使用しない場合

• /aep-build のフェーズ 5 では、組み込みの評価ループを使用してください（executor.spawn_evaluator、検証用 JSON、スコアリングフレームワークが含まれています）。
• 主観的な品質を評価する場合は、このスキルを使用しないでください。このスキルは、事実の正確性と完全性を検証するものであり、見た目の良し悪しを判断するものではありません。ユーザビリティやデザイン品質のレビューには、HCI 理論に基づくヒューリスティックな健全性チェックである /aep-design-lens を使用してください。そのデザイン品質のレビューは、validate の事実確認を補完します。
• 小さな変更の場合は、このスキルを使用しないでください。単一ファイルの編集や誤字の修正には、3 エージェントによる検証は不要です。

---

次のステップ

検証後、適切な後続スキルに進みます。

Product context validated → /aep-dispatch
Design validated          → /aep-launch
Code validated            → create PR (or /aep-build Phase 9)
Document validated        → publish/share