quality-playbook

Quality Playbook Generator

プラン概要 — まずこれを読み、その後ユーザーに説明してください

このスキルの他のセクションを読む前に、プランとその依存関係を理解してください。各フェーズは、次のフェーズが依存する成果物を生成します。フェーズを飛ばしたり急いだりすると、後続のすべてのフェーズが不完全な情報をもとに作業することになります。

フェーズ 0（前回実行の分析）: 以前の品質実行結果が存在する場合は、その発見事項をシードデータとして読み込みます。これは自動的に行われ、再実行の場合にのみ適用されます。

フェーズ 1（探索）: まず v1.5.3 のドキュメント取り込みを実行します（python -m bin.reference_docs_ingest <target> で reference_docs/ を走査します。cite/ のファイルは quality/formal_docs_manifest.json のレコードを生成し、トップレベルのファイルは reference_docs_ingest.load_tier4_context(<target>) によって Tier 4 のコンテキストとして読み込まれます）。その後、次の三段階でコードベースを探索します。ドメイン知識に基づく自由な探索、ドメイン知識によるリスク分析、そして選択された構造化された探索パターンです。すべての発見事項は quality/EXPLORATION.md に書き出します。このファイルが基盤であり、フェーズ 2 はこれを主要な入力として読み込みます。

フェーズ 2（生成）: EXPLORATION.md を読み込み、品質成果物を生成します。具体的には、要件、憲章、機能テスト、コードレビュー手順、統合テスト、仕様監査手順、TDD 手順です。（対象リポジトリのルートにある AGENTS.md は、フェーズ 2 であなたが生成するのではなく、オーケストレーターがフェーズ 6 の後に生成します。契約内容については後述の「ファイル 6」を参照してください。）

フェーズ 3（コードレビュー）: HEAD に対して三段階のコードレビューを実行します。確認されたすべてのバグについて回帰テストを書き、パッチを生成します。

フェーズ 4（仕様監査）: 三つの独立した AI 監査役が、要件に照らしてコードをレビューします。検証プローブを用いてトリアージを行います。トリアージの後、同じ Council が v1.5.3 の Layer-2 意味的引用チェックを実行します。レビュアーごとに一つのプロンプトを使い、Tier 1/2 のすべての引用について REQ ごとの構造化された判定を行い、結果を quality/citation_semantic_check.json に出力します。新たに判明した発見事項については回帰テストを書きます。

フェーズ 5（照合）: ループを閉じます。コードレビューと仕様監査で見つかったすべてのバグを追跡し、回帰テストを行うか、明示的に除外します。TDD の red-green サイクルを実行し、完全性レポートを確定します。

フェーズ 6（検証）: 生成されたすべての成果物に対してセルフチェックのベンチマークを実行します。内部の一貫性、バージョンスタンプの正しさ、収束を確認します。

フェーズ 7（提示・探索・改善）: 結果を、一覧しやすいサマリーテーブルでユーザーに提示し、任意の成果物について詳細確認を提供し、改善の選択肢（反復戦略、要件の洗練、統合テストの調整）のメニューを示します。このフェーズは、ユーザーが品質システムの主導権を握る対話的なフェーズです。

見つかったすべてのバグは要件までたどれ、すべての要件は探索の発見事項までたどれる必要があります。

重要な依存関係の連鎖: 探索の発見事項 → EXPLORATION.md → 要件 → コードレビュー + 仕様監査 → バグの発見。浅い探索からは抽象的な要件しか生まれず、抽象的な要件ではバグを見逃します。バグを見つけられるかどうかは探索フェーズで決まります。

最初に必ず行うこと: 上記のプランを読んで理解したら、次のメッセージをユーザーに表示してください。その後、プランを自分の言葉で説明してください。何を行うか、各フェーズが何を生成するか、そして探索フェーズが最も重要な理由を説明してください。探索は、まずドメインに基づく自由な調査から始まり、続いてこの種のシステムで何が問題になりうるかを推論するドメイン知識によるリスク分析を行い、さらに選択された構造化パターンで補完されることを強調してください。プランを一字一句コピーせず、理解を示すように言い換えてください。

Quality Playbook v1.5.6 — by Andrew Stellman https://github.com/andrewstellman/quality-playbook

特定のコードベースに合わせた完全な品質システムを生成します。ソースコードから機械的に作業するテストスタブ生成ツールとは異なり、このスキルはまずプロジェクトを探索します。ドメイン、アーキテクチャ、仕様、障害の履歴を理解したうえで、発見した内容に基づいた品質プレイブックを作成します。

このスキルの実行方法 — v1.5.4 セルフエンコード型呼び出し契約

オペレーターがこのスキル（または QPB がインストールされた任意の対象）を渡し、**「Run the Quality Playbook」**と指示した場合（「これはブートストラップ実行です」「自分自身に対して実行してください」「self-audit」などの補足が付くこともあります）、このセクションに従うべき内容がすべて記載されています。オペレーターから追加の指示を受け取る必要はありません。正規の呼び出し方法、デフォルト設定、ガードレール、出力契約はすべてここにあります。

実行モードを選択する

QPB は 2 つの実行形態で提供されます。実行環境に合ったものを選んでください。選択を誤ると、2026-04-30 のブートストラップテストで明らかになった codex-on-codex の間接実行の問題が発生します。

モード	該当する場合	実行内容
A. スキル直接実行（UI コンテキスト）	あなたはこのスキルを自分のチャットで受け取ったコーディングエージェント（Claude Code、Cursor、Copilot、Codex デスクトップなど）です。実行環境そのものが推論ループであり、ファイルの読み取り・書き込み・判断をあなた自身が行います。	phase_prompts/ にある外部化されたフェーズプロンプトを使い、Phase 1 から Phase 6 まで自分で進めます。成果物は対象の quality/ ディレクトリに直接書き込みます。サブプロセスやランナーは使用しません。
B. ランナー駆動（CLI 自動化）	オペレーターが意図的に python3 -m bin.run_playbook を実行している場合です。複数の対象をバッチ処理する、ヘッドレス CI を実行する、またはこの文章を読んでいるモデルとは別のモデルにフェーズ作業を振り分ける目的などがあります。	オーケストレーターがフェーズごとに CLI エージェント（claude、copilot、codex、cursor）を起動します。あなた（またはこの文章を読んでいる人）はオペレーター側の制御ループであり、フェーズごとの推論を行う主体ではありません。

両モードは同じフェーズプロンプトの内容を使用します。 リポジトリルートにある phase_prompts/*.md ファイルが唯一の情報源であり、bin/run_playbook.py::_load_phase_prompt によって読み込まれ、モード A の手順でも直接読まれます。両モードの違いは、誰が実行を主導するかだけです。モード A ではあなたが、モード B ではサブプロセスで CLI エージェントを起動するオーケストレーターが主導します。

迷った場合はモード A を選んでください。 オペレーターがランナー駆動の実行を望んでいたなら、自分でランナーを動かしていたはずです。「Run the Quality Playbook」とチャットに貼り付けたのであれば、あなたに主導してほしいということです。以下の「モード B」セクションは、オペレーターが明示的にランナーを呼び出した場合に何をすべきかを説明しています。

モード A — スキル直接の手順（UI コンテキスト）

オペレーターのプロンプトは単に 「Run the Quality Playbook」（または「run on itself」「self-audit」など）です。あなたがすべてのフェーズをインラインで進めます。

Phase 1 から 6 まで、順番に次を行います。

1. フェーズプロンプトを読み込む。 phase_prompts/phaseN.md を読みます（references/ について後述するものと同じインストール場所のフォールバック一覧で解決します）。phase1.md では、{seed_instruction}（シードを許可する場合は空文字列となる「Phase 0/0b をスキップする」旨の前置き）と {role_taxonomy}（後述のロールタクソノミーから描画されたタクソノミーブロック）を置換します。phase2.md から phase6.md は純粋なリテラルなので、そのまま読み込みます。
2. プロンプトに従ってフェーズを実行する。 プロンプトが指定する入力を読み、分析を行い、対象の quality/ ディレクトリに成果物を書き込みます。
3. フェーズ終了の境界で停止する。 すべてのフェーズプロンプトは「IMPORTANT: Do NOT proceed to Phase N+1」という指示で終わります。これを守ってください。次のフェーズへの移行は、オペレーターがその旨を伝えることで行われます。

オーケストレーターによる構造的な安全装置がない中で、ランナーが強制する「ソースを変更しない」という不変条件についても、あなたが責任を持ちます。対象の quality/ ディレクトリの外にあるファイルは一切変更しないでください。 モード B ではゲートがこれを検出しますが、モード A ではあなた自身がゲートです。2026-04-30 のブートストラップテストでは、Phase 2 の LLM が対象ルートの AGENTS.md を変更したことで失敗しました。同じ失敗モードはモード A でも起こり得ます。

ブートストラップ実行（自己監査）のモード A については、後述の「ブートストラップモード」を参照してください。違いは、対象が QPB リポジトリ自体であることだけです。読み込んだ phase_prompts/ のファイルを引用してください。

Mode A の対象範囲 — 対象となる内容と Mode B 専用の内容

Council 2026-04-30 P1-3：上記のフェーズごとの手順では、Mode A の対象をフェーズ 1～6としています。以下の機能は意図的に Mode B 専用です。オペレーターがこれらを希望する場合、自分で実行しようとせず、runner を案内してください。

• フェーズ 0／フェーズ 0b（過去の実行からのシード注入）。 オーケストレーターがシードの検出、過去の実行のスキャン、シードプロンプトの注入を処理します。Mode A では、すべての実行を --no-seeds として扱います（フェーズ 0／0b を完全にスキップし、フェーズ 1 から開始します）。オペレーターがシード駆動の探索を明示的に求めた場合は、Mode B に引き継ぎます（python3 -m bin.run_playbook --with-seeds <target>）。
• フェーズ 7（対話形式の Present／Explore／Improve）。 このフェーズでは、生成されたアーティファクトについてオペレーターと対話します。phase_prompts/ にあらかじめ用意されたプロンプトはありません。Mode A でフェーズ 6 が完了したら、アーティファクトの概要表をインラインで提示し（ファイル一覧は下記「この実行で生成されるもの」を参照）、次に何を探索するかはオペレーターに会話を通じて決めてもらいます。これがフェーズ 7 そのものです。起動するオーケストレーターのサブプロセスはありません。
• イテレーション戦略（gap／unfiltered／parity／adversarial）。 イテレーションでは、戦略固有の補足を加えてプレイブックを再実行します。Mode A では、フェーズ 6 が問題なく完了した後、イテレーションを Mode B に引き継ぎます。python3 -m bin.run_playbook --next-iteration --strategy <name> <target> を実行します。イテレーション用プロンプト（phase_prompts/iteration.md）は唯一の信頼できる情報源ですが、イテレーションのオーケストレーションループ（gap → unfiltered → parity → adversarial の順に実行）は runner の役割です。フェーズ 6 の後にイテレーションを希望する Mode A のオペレーターには、次のように伝えてください。「フェーズ 6 は完了しました。4 つすべてのイテレーション戦略を実行するには python3 -m bin.run_playbook --full-run <target> を実行してください。または、--next-iteration --strategy gap を指定して戦略を 1 つ選べます。」

Mode A でオペレーターがこれらの機能を求め、その依頼が曖昧な場合（例：「イテレーションも実行してください」）、独自の判断で進めず、モードの引き継ぎを明確に案内してください。独自の判断で進めると、プロンプトの内容が runner の標準ループから逸脱するためです。

Mode B — runner 主導の実行（CLI 自動化）

オペレーター自身が python3 -m bin.run_playbook を実行します（通常は、バッチ処理、ヘッドレス CI、またはフェーズごとの作業を別のモデルに割り当てることが目的です）。bin/run_playbook.py のオーケストレーターは、フェーズごとに CLI エージェントを起動し、外部化されたフェーズプロンプトを渡して、結果を集約します。

標準的な実行方法

オーケストレーターがエントリーポイントです。必ず Python モジュールとして実行してください。

python3 -m bin.run_playbook <target>

スクリプト形式で実行してはいけません（python bin/run_playbook.py ...）。相対インポートにはパッケージとしての実行が必要なため、ランタイムガードによって EX_USAGE=64 で終了します。

<target> は監査対象プロジェクトのパスです。ブートストラップ実行（target が QPB リポジトリそのもの）の場合は、リポジトリのルートから . を渡します。それ以外の target では、対象リポジトリのルートへのパスを渡します。

デフォルトの動作（フラグなし）

オプションを指定せずに実行すると、フル実行が開始されます。全 6 フェーズ（Explore → Generate → Code Review → Spec Audit → Reconciliation → Verify）を実行した後、4 つすべてのイテレーション戦略（gap → unfiltered → parity → adversarial）を同一セッション内で同期的に実行します。既存の quality/ ディレクトリは、新しい実行の開始前に quality/previous_runs/<TIMESTAMP>/ へ自動的にアーカイブされます。

これが標準的なオペレーター向けの実行方法です。フラグの追加について許可を求めないでください。デフォルトのままで問題ありません。

オプションを指定せずに実行すると、オーケストレーターは v1.5.3 と比べたコストの変化（従来のデフォルトである「フェーズ 1 のみ」の約 5～10 倍）を示す 1 行のバナーを stderr に出力します。このバナーは情報提供のみを目的としています。そのまま表示させてください。

共通のオーバーライド

オペレーターから具体的な指定があった場合にのみ使用します。

必要なこと	フラグ	効果
単一フェーズを実行する	--phase N（N ∈ 1..6）	--phase 1 を指定すると、v1.5.3 の「探索のみ」パターンを再現します。
イテレーション戦略をスキップする	--iterations を省略し、--phase 1,2,3,4,5,6 を渡す	フェーズは実行されますが、イテレーションは実行されません。
特定のイテレーション	--strategy <name> --next-iteration	選択した戦略で、既存の quality/ 実行に対してイテレーションします。
複数のターゲット	複数の位置引数のターゲットを渡す	それぞれを独立して実行します。
フェーズごとの CLI エージェント	--claude / --copilot / --codex / --cursor	オーケストレーターが起動する CLI ランナーを選択します。デフォルトは --copilot です。v1.5.4 では --cursor ランナー（cursor-cli 3.1 以降）が追加されました。

ランナー主導の実行が途中で終了・中断した場合の復旧

Council 2026-04-30 P1-4：実行中断後の後片付けに関するオペレーター向けガイダンスは、以下のブートストラップモードのセクション（「ブートストラップ実行時のオペレーター向け注意事項」）に記載されています。Mode B でも復旧手順は同じです。git restore quality/ を実行して Phase 1/2 の途中出力を破棄し、その後に再実行してください。「整理」のために quality/ 外のファイルを絶対に編集しないでください。次回の実行でソース未変更の不変条件に抵触します。詳しい手順については、ブートストラップモードの注意事項を参照してください。この手順は、セルフ監査実行中に中断した場合でも、外部ターゲットに対する実行中に中断した場合でも同じです。

ブートストラップモード（QPB 自身に対する QPB の実行）

オペレーターが「これはブートストラップ実行です」、「QPB 自身に対して QPB を実行します」、または「セルフ監査」と指示した場合：

1. 作業ディレクトリが QPB リポジトリのルートであることを確認します（そうでなければ、そこへ cd します）。
2. python3 -m bin.run_playbook . を実行します。正規の形式は同じで、ターゲットは . です。
3. オーケストレーターが既存の quality/ ツリーを自動的に quality/previous_runs/<TIMESTAMP>/ にアーカイブするため、手動でクリーンアップする必要はありません。

実行は他のターゲットの場合と同じように進みます。唯一の違いは、監査対象がプレイブック自体であるため、生成される成果物に QPB 自身の品質システムが記述されることです。

ブートストラップ実行時のオペレーター向け注意事項 — 途中で終了・中断した場合の復旧。 以前のブートストラップ実行が途中で終了した場合（例：ソース未変更の不変条件に抵触した、フェーズのプロンプトでエラーが発生した、オペレーターが Ctrl-C を押した）、作業ツリーには書きかけの quality/ ディレクトリと、放棄されたアーカイブを示す quality/previous_runs/<TIMESTAMP>/.partial センチネルが残っている可能性があります。再実行する前に git restore quality/ を実行し（必要であれば、完全にクリーンな状態にするため git clean -fd quality/ も実行します）、中断した実行で生成された未コミットの Phase 1/2 の出力を削除してください。オーケストレーターが新たに未変更状態の quality/ ツリーをアーカイブし、クリーンな状態から実行を開始します。「整理」のために quality/ 外のファイルを絶対に編集しないでください。quality/ 外のファイルはすべて QPB のソースです。後片付けのためにこれらに手を加えると、次回の実行でソース未変更の不変条件に抵触します。2026-04-30 のブートストラップテストでは、まさにこの復旧に関する問題が明らかになりました。オペレーターは Phase 2 の中断によって書きかけの quality/ が残った状態で、復元せずに再実行したため、古い Phase 1 の成果物が残り、次の実行時のアーカイブ処理に混乱が生じました。

v1.5.4 の仕組み（ポインター形式。設計ドキュメントの内容を重複して記載しません）

v1.5.3 からの変更点をポインター形式で示します（正式なアーキテクチャは docs/design/QPB_v1.5.4_Design.md の Part 1 に記載されています）。

• Phase 1 で quality/exploration_role_map.json を生成します — 探索中に、AI 主導でファイルごとにロールをタグ付けします。対象範囲内の各ファイルに、分類体系（skill-prose、skill-reference、skill-tool、code、test、docs、config、fixture、formal-spec、playbook-output）からロールを割り当てます。このロールマップが、後続のすべてのパイプラインの有効化判断を左右します。
• INDEX.md は schema_version: "2.0" を使用し、ロールごとの件数と割合を示す target_role_breakdown フィールドを備えます。v1.5.3 の target_project_type 列挙型は廃止されます（過去のアーカイブは引き続き読み取り可能です）。
• パイプラインはプロジェクトタイプのラベルではなく、ロールマップに基づいて有効化されます。 4 パスのスキル派生パイプラインは、skill-prose／skill-reference のタグが付いたファイルを対象に実行されます。コードレビューのパイプラインは、code のタグが付いたファイルを対象に実行されます。散文からコードへの乖離チェックは、skill-tool のタグが付いたファイルを対象に実行されます。ロールマップで該当ロールが 0 件の場合、そのパイプラインは正常に何も実行せず終了します。Code／Skill／Hybrid の三分法はありません。両方の対象範囲が存在する場合は、両方のパイプラインが実行されます（「常に Hybrid として後続処理を行う」モデル）。
• アーカイブディレクトリは quality/previous_runs/ です（v1.5.3 では quality/runs/）。旧パスのレガシーアーカイブも引き続き読み取り可能です。
• Phase 6 の終了時に再編成を行い、中間成果物を quality/workspace/ に移動します。これにより、トップレベルの quality/ ディレクトリには正規の成果物（REQUIREMENTS.md、BUGS.md など）が主に置かれます。ゲートのパスリゾルバーは両方の構成から読み取ります。

プロンプト側の推論でこれらを改めて導出する必要はありません。オーケストレーターのプロンプトにはすでに反映されています。ここに要約したアーキテクチャと矛盾するフェーズプロンプトがある場合は、そのフェーズプロンプトに従ってください。フェーズごとの契約については、フェーズプロンプトが正式な情報源です。

ガードレール（機械で検証可能なハード制約）

これらは提案ではありません。オーケストレーターによって強制され、違反すると実行が中止されます。

1. 同期実行 — サブエージェントへの委任は禁止。 すべてのフェーズを、同じセッション内で自分自身で実行してください。Task ツール、サブエージェントの呼び出し、バックグラウンドエージェントの起動、または「フェーズ 2〜6 をワーカーに委任する」といったパターンは使用しないでください。B-15 の障害モードは実際に発生しています。フェーズ 1 は完了するものの、親セッションを失った委任先のエージェントでフェーズ 2〜6 がひそかに停止し、ランナーは自ら -PARTIAL と記録するため、オペレーターは問題があったことを把握できません。v1.5.4 のプロンプトではこれを明示的に禁止しています。
2. 実行中に QPB のソースをパッチしないでください。 実行中に bin/、.github/skills/、agents/、references/、SKILL.md、schemas.md、または AGENTS.md にバグを見つけた場合は、停止して報告してください。ファイルと行番号を示し、問題を説明し、修正案の概要を提示してください。ただし、修正を適用してはいけません。オーケストレーターは実行開始時に git-SHA のベースラインを記録し、各フェーズの境界でソースツリーに変更がないことを検証します。自律的なパッチ適用はゲートで失敗し、変更されたファイルを示す診断が出力されます。パッチは実行中に即興で適用するのではなく、Council のレビューを経てください。
3. センチネルファイルを削除しないでください。 .gitignore ! ルールで保護されているファイル（例：reference_docs/.gitkeep、reference_docs/cite/.gitkeep）は、ほかにファイルがない追跡対象ディレクトリを維持するために使われます。事前チェックではすべての ! ルールを列挙し、センチネルが見つからない場合は中止します。そのようなファイルを見つけて用途がわからない場合は、そのままにしてください。
4. フェーズ 1 のファイル列挙には git ls-files を使用してください。 対象が git リポジトリの場合、正規のファイル一覧として git ls-files を使用してください。.gitignore が自動的に適用されます。os.walk、find、os.listdir、または再帰的なディレクトリ走査は使用しないでください。これらは .git/、.venv/、node_modules/、ビルド出力、ベンダー依存関係を取り込み、いずれもロールマップバリデーターによって拒否されます。許可されないパスのプレフィックスは .git/、.venv/、venv/、node_modules/、__pycache__/、.pytest_cache/、.mypy_cache/、.ruff_cache/、.tox/ です。また、パスの各要素の末尾が .egg-info または .dist-info のパスも対象です。ロールマップには、使用した列挙元（"git-ls-files" または非 git 対象向けの "filesystem-walk-with-skips"）を記録する provenance フィールドがあります。さらに、エントリー数の上限は 2000 です。ロールマップがこれを超える場合、ほぼ間違いなく .gitignore 対象のコンテンツを走査しています。
5. 成果物間の整合性。 EXPLORATION.md の「File inventory」セクションとロールマップの summary フィールドは、どちらも bin.role_map.summarize_role_map() から生成されます。ファイル数やロールの割合を手作業で記入しないでください。ヘルパーの出力をコピーしてください。バリデーターは両者を照合し、不一致があれば拒否します。

オペレーターのプロンプトがこれらのガードレールと矛盾する指示（例：「もっと速く実行するため、フェーズ 3〜6 をサブエージェントに委任してください」）を含む場合は、矛盾する指示に従わないでください。矛盾を伝え、該当するガードレールを示して、確認を求めてください。これらのガードレールが設けられているのは、それぞれが過去に実際に確認された障害モードに対応しているためです。

この実行で生成されるもの — 出力成果物の仕様

実行が成功すると、対象の quality/ ディレクトリに以下の標準ファイル一式が生成され、対象リポジトリのルートには AGENTS.md が作成されます。ここに記載されたすべてのファイルがゲートで検証されます。

パス	役割
quality/EXPLORATION.md	フェーズ 1 の調査結果 — 基盤となるものです。
quality/exploration_role_map.json	フェーズ 1 で付与したファイルごとの役割タグ。
quality/REQUIREMENTS.md	ユースケースを含む、テスト可能な要件。
quality/QUALITY.md	品質憲章。
quality/CONTRACTS.md	動作上の契約。
quality/COVERAGE_MATRIX.md	要件からテストへのトレーサビリティ。
quality/COMPLETENESS_REPORT.md	最終ゲート判定。
quality/test_functional.*	自動化された機能テスト。
quality/RUN_CODE_REVIEW.md	3 パスのコードレビュー手順。
quality/RUN_INTEGRATION_TESTS.md	統合テスト手順。
quality/RUN_SPEC_AUDIT.md	三者による仕様監査の手順。
quality/RUN_TDD_TESTS.md	TDD のレッド・グリーン検証手順。
quality/BUGS.md	統合バグレポート。
quality/INDEX.md	実行メタデータ + 役割の内訳 + ゲート判定。
quality/PROGRESS.md	フェーズごとのチェックポイントログ。
quality/previous_runs/<TIMESTAMP>/	過去の実行があれば、そのアーカイブ。
quality/workspace/	パイプラインの中間成果物（制御プロンプト、コードレビュー、仕様監査、4 パスのパイプライン出力など）。
AGENTS.md（対象リポジトリのルート）	フェーズ 6 の後に生成される、プロジェクトごとのガイド。QPB が管理するコピーを今後の実行で検出できるよう、QPB センチネルマーカーが付与されます。

quality/INDEX.md のゲート判定（pass / partial / fail）は、実行結果をオペレーター向けに要約したものです。pass 以外の場合は、実行を完了と見なす前に、その理由を明示してください。

参照ファイルの場所

このスキルは references/ ディレクトリ内のファイル（例：references/iteration.md、references/review_protocols.md）を参照します。場所はスキルのインストール方法によって異なります。参照ファイルが記載されている場合は、以下のパスを順に確認し、最初に見つかったものを使用してください。

1. references/（SKILL.md からの相対パス — スキルのディレクトリから実行する場合に使用できます）
2. .claude/skills/quality-playbook/references/（Claude Code のインストール先）
3. .github/skills/references/（GitHub Copilot のフラット形式のインストール先）
4. .github/skills/quality-playbook/references/（Copilot の別形式のインストール先）

このスキルに記載される参照ファイルはすべて、短縮形 references/filename.md を使用します。相対パスで解決できない場合は、上記のフォールバックリストを順に確認してください。

これが必要な理由

ほとんどのソフトウェアプロジェクトにはテストがありますが、品質のシステムを備えているプロジェクトは多くありません。テストではコードが動作するかを確認します。品質システムは、より難しい問いに答えます。このプロジェクトで「正しく動作する」とは何を意味するのか。テストでは検出できない、どのような失敗が起こり得るのか。人間であれ AI であれ、すべての開発者がこのコードに手を加える前に知っておくべきことは何か。

品質プレイブックがなければ、新しい貢献者も、新しい AI セッションも、毎回ゼロから始めることになります。何が重要かを推測し、見栄えはよいものの実際のバグを検出できないテストを書き、すでに発見され修正された失敗のパターンを何カ月も後になって再発見します。品質プレイブックは、品質基準を明確にし、永続させ、後続の作業に引き継ぎます。

このスキルが生成するもの

繰り返し利用できる品質システムを構成する9つのファイル：

ファイル	目的	重要な理由	コードを実行しますか？
quality/QUALITY.md	品質の基本方針 — カバレッジ目標、目的適合性のシナリオ、形骸化の防止	すべてのAIセッションで最初に読み込みます。「十分に良い」とは何かを示すため、AIが推測する必要がありません。	いいえ
quality/REQUIREMENTS.md	プロジェクト概要、ユースケース、説明を含む、テスト可能な要件 — 5段階のパイプライン（契約抽出 → 導出 → 検証 → 完全性確認 → 説明）で生成	コードレビューの第2・第3パスの基盤です。要件がなければ、レビューは構造上の異常（上限約65%）に限られます。要件があれば、コードを読むだけでは見つけられない意図違反 — 欠落によるバグ、ファイル間の矛盾、設計上の不足 — を検出できます。	いいえ
quality/test_functional.*	仕様から導出した自動機能テスト	安全網となります。単にコードの動作を確かめるのではなく、仕様に記載された期待動作に結び付いたテストです。プロジェクトの言語に合わせて、test_functional.py（Python）、FunctionalSpec.scala（Scala）、functional.test.ts（TypeScript）、FunctionalTest.java（Java）などを使用します。	はい
quality/RUN_CODE_REVIEW.md	3パスのコードレビュープロトコル：構造レビュー、要件検証、要件間の整合性確認	構造レビューだけでは、実際の不具合の約35%を見逃します。3パスのパイプラインでは、要件検証と整合性チェックを追加します。実験の証拠により、構造レビューのすべての条件で見つからなかったバグも検出できることが示されています。	いいえ
quality/RUN_INTEGRATION_TESTS.md	統合テストプロトコル — すべてのバリアントを対象とするエンドツーエンドのパイプライン	ユニットテストは合格しても、実際の外部サービスを使ったエンドツーエンドでシステムは本当に動作するでしょうか？	はい
quality/BUGS.md	パッチを含む、統合されたバグ報告	再現手順、仕様上の根拠、重大度、パッチへの参照を含め、確認済みのバグをすべて1か所にまとめます。何が壊れていて、どう検証するかを示す唯一の信頼できる情報源です。	いいえ
quality/RUN_TDD_TESTS.md	TDDのレッド・グリーン検証プロトコル	各バグが実在すること（パッチ適用前のコードでテストが失敗すること）と、各修正が機能すること（パッチ適用後にテストが合格すること）を証明します。バグ報告だけの場合より強い証拠となり、メンテナーはFAIL→PASSの実演を信頼します。	はい
quality/RUN_SPEC_AUDIT.md	3モデルによる仕様監査プロトコル	1つのAIモデルですべてを検出することはできません。異なる盲点を持つ3つの独立したモデルを使うことで、いずれか1つだけでは見逃される不具合を検出できます。	いいえ
AGENTS.md	このプロジェクトに取り組むあらゆるAIセッション向けの初期コンテキスト	「まずこれを読む」ためのファイルです。これがないと、AIセッションは状況を把握するだけで最初の1時間を費やしてしまいます。	いいえ

さらに、出力ディレクトリとして quality/code_reviews/、quality/spec_audits/、quality/results/、quality/history/ があります。

このパイプラインでは、補助成果物も生成します。quality/PROGRESS.md（累積BUGトラッカー付きのフェーズごとのチェックポイントログ）、quality/CONTRACTS.md（動作契約）、quality/COVERAGE_MATRIX.md（トレーサビリティ）、quality/COMPLETENESS_REPORT.md（最終ゲート）、quality/VERSION_HISTORY.md（レビューログ）です。フェーズ7では、反復的な改善に向けて quality/REVIEW_REQUIREMENTS.md（対話型レビューのプロトコル）と quality/REFINE_REQUIREMENTS.md（要件の改善パスのプロトコル）を追加で生成することもできます。

重要な成果物は、要件ファイルと機能テストファイルの2つです。要件ファイル（quality/REQUIREMENTS.md）はコードレビュープロトコルの検証パスと整合性確認パスに入力されるため、コードレビューで構造上の異常を超える問題を検出できるようになります。機能テストファイル（プロジェクトの言語とテストフレームワークの規約に合わせた名前を使用）は、自動化された安全網です。Markdownのプロトコルは、人間とAIエージェント向けのドキュメントです。

完全な成果物一覧

品質ゲート（quality_gate.py）は、以下の成果物を検証します。ゲートが成果物をチェックする場合、このスキルはその作成を指示する必要があります。以下が正式な一覧です。ここに記載されていない成果物はゲートで強制チェックしてはならず、ゲートのチェック項目はすべて、ここに記載された成果物に対応している必要があります。

成果物	場所	必須？	作成フェーズ
正式ドキュメントマニフェスト（v1.5.3）	quality/formal_docs_manifest.json	はい	フェーズ 1（bin/reference_docs_ingest.py）
要件マニフェスト（v1.5.3）	quality/requirements_manifest.json	はい	フェーズ 2
ユースケースマニフェスト（v1.5.3）	quality/use_cases_manifest.json	はい	フェーズ 2
バグマニフェスト（v1.5.3）	quality/bugs_manifest.json	バグが見つかった場合	フェーズ 3/4/5
引用セマンティックチェック（v1.5.3）	quality/citation_semantic_check.json	はい	フェーズ 4（レイヤー 2 評議会）
探索結果	quality/EXPLORATION.md	はい	フェーズ 1
品質規約	quality/QUALITY.md	はい	フェーズ 2
要件（UC 識別子）	quality/REQUIREMENTS.md	はい	フェーズ 2
振る舞いの契約	quality/CONTRACTS.md	はい	フェーズ 2
機能テスト	quality/test_functional.*	はい	フェーズ 2
回帰テスト	quality/test_regression.*	バグが見つかった場合	フェーズ 3
コードレビュー手順	quality/RUN_CODE_REVIEW.md	はい	フェーズ 2
統合テスト手順	quality/RUN_INTEGRATION_TESTS.md	はい	フェーズ 2
仕様監査手順	quality/RUN_SPEC_AUDIT.md	はい	フェーズ 2
TDD 検証手順	quality/RUN_TDD_TESTS.md	はい	フェーズ 2
バグトラッカー	quality/BUGS.md	はい	フェーズ 3
カバレッジマトリクス	quality/COVERAGE_MATRIX.md	はい	フェーズ 2
完了レポート	quality/COMPLETENESS_REPORT.md	はい	フェーズ 2（ベースライン）、フェーズ 5（最終判定）
進捗トラッカー	quality/PROGRESS.md	はい	全期間
AI ブートストラップ	AGENTS.md（対象リポジトリのルート）	はい	フェーズ 6 の後、オーケストレーターが生成 — フェーズ 2 の成果物ではありません
バグの詳細記録	quality/writeups/BUG-NNN.md	バグが見つかった場合	フェーズ 5
回帰パッチ	quality/patches/BUG-NNN-regression-test.patch	バグが見つかった場合	フェーズ 3
修正パッチ	quality/patches/BUG-NNN-fix.patch	任意	フェーズ 3
TDD トレーサビリティ	quality/TDD_TRACEABILITY.md	バグに red フェーズの結果がある場合	フェーズ 5
TDD サイドカー	quality/results/tdd-results.json	バグが見つかった場合	フェーズ 5
TDD red フェーズのログ	quality/results/BUG-NNN.red.log	バグが見つかった場合	フェーズ 5
TDD green フェーズのログ	quality/results/BUG-NNN.green.log	修正パッチが存在する場合	フェーズ 5
統合テストのサイドカー	quality/results/integration-results.json	統合テストの実行時	フェーズ 5
機械的検証スクリプト	quality/mechanical/verify.sh	はい（ベンチマーク）	フェーズ 2
検証レシート	quality/results/mechanical-verify.log + .exit	はい（ベンチマーク）	フェーズ 5
トリアージプローブ	quality/spec_audits/triage_probes.sh	トリアージの実行時	フェーズ 4
コードレビューレポート	quality/code_reviews/*.md	はい	フェーズ 3
仕様監査レポート	quality/spec_audits/*auditor*.md + *triage*	はい	フェーズ 4
再チェック結果（JSON）	quality/results/recheck-results.json	再チェックの実行時	再チェック
再チェックの概要（MD）	quality/results/recheck-summary.md	再チェックの実行時	再チェック
シードチェック	quality/SEED_CHECKS.md	フェーズ 0b を実行した場合	フェーズ 0b
実行メタデータ	quality/results/run-YYYY-MM-DDTHH-MM-SS.json	はい	フェーズ 1（作成）、全期間（更新）

サイドカー JSON のライフサイクル： tdd-results.json を確定する前に、すべてのバグの詳細記録を作成してください。サイドカーの writeup_path フィールドは、プレースホルダーではなく、実在するファイルを参照している必要があります。同様に、integration-results.json を作成する前に、統合テストを実行して結果を収集してください。

Sidecar JSON の標準例

quality/results/tdd-results.json — ゲートでは、フィールドの有無だけでなく、フィールド名も検証します。

{
  "schema_version": "1.1",
  "skill_version": "1.5.6",
  "date": "2026-04-12",
  "project": "repo-name",
  "bugs": [
    {
      "id": "BUG-001",
      "requirement": "REQ-003",
      "red_phase": "fail",
      "green_phase": "pass",
      "verdict": "TDD verified",
      "fix_patch_present": true,
      "writeup_path": "quality/writeups/BUG-001.md"
    }
  ],
  "summary": {
    "total": 3, "confirmed_open": 1, "red_failed": 0, "green_failed": 0, "verified": 2
  }
}

verdict は "TDD verified"、"red failed"、"green failed"、"confirmed open"、"deferred" のいずれかである必要があります。date は ISO 8601（YYYY-MM-DD）形式で、プレースホルダーではなく、未来の日付でもない必要があります。

quality/results/integration-results.json：

{
  "schema_version": "1.1",
  "skill_version": "1.5.6",
  "date": "2026-04-12",
  "project": "repo-name",
  "recommendation": "SHIP",
  "groups": [{ "group": 1, "name": "Group 1", "use_cases": ["UC-01"], "result": "pass", "tests_passed": 3, "tests_failed": 0, "notes": "" }],
  "summary": { "total_groups": 12, "passed": 11, "failed": 1, "skipped": 0 },
  "uc_coverage": { "UC-01": "covered_pass", "UC-02": "not_mapped" }
}

recommendation は "SHIP"、"FIX BEFORE MERGE"、"BLOCK" のいずれかである必要があります。uc_coverage では、REQUIREMENTS.md の UC 識別子をカバレッジのステータスに対応付けます。

実行メタデータ

プレイブックを実行するたびに、quality/results/run-YYYY-MM-DDTHH-MM-SS.json にタイムスタンプ付きのメタデータファイルが作成されます。これにより、複数モデルの比較と実行履歴の追跡が可能になります。

ライフサイクル： フェーズ 1 の開始時にこのファイルを作成します。各フェーズの完了時に、phases_completed、bug_count、end_time を更新します。最後の更新は、終了ゲートの後に行います。

{
  "schema_version": "1.0",
  "skill_version": "1.5.6",
  "project": "repo-name",
  "model": "claude-sonnet-4-6",
  "model_provider": "anthropic",
  "runner": "claude-code",
  "start_time": "2026-04-16T10:30:00Z",
  "end_time": "2026-04-16T11:45:00Z",
  "duration_minutes": 75,
  "phases_completed": ["Phase 0b", "Phase 1", "Phase 2", "Phase 3", "Phase 4", "Phase 5"],
  "iterations_completed": ["gap", "unfiltered", "parity", "adversarial"],
  "bug_count": 12,
  "bug_severity": { "HIGH": 2, "MEDIUM": 5, "LOW": 5 },
  "gate_result": "PASS",
  "gate_fail_count": 0,
  "gate_warn_count": 2,
  "notes": ""
}

必須フィールド： schema_version、skill_version、project、model、start_time。その他のフィールドは、実行の進行に合わせて入力されます。model には、正確なモデル文字列（例："claude-sonnet-4-6"、"gpt-4.1"、"claude-opus-4-6"）を指定してください。runner には、プレイブックの実行に使用したツール（例："claude-code"、"copilot-cli"、"cursor"、"cowork"）を指定します。duration_minutes は end_time - start_time から計算されます。モデルまたは runner を特定できない場合は、"unknown" を使用してください。

使用方法

このプレイブックは、一度に 1 つのフェーズを実行するように設計されています。 各フェーズはクリーンなコンテキストウィンドウを持つ独立したセッションで実行され、ファイルをディスクに出力します。次のフェーズでは、そのファイルを読み込みます。この方法では、すべてのフェーズを一度に実行するよりも、はるかに良い結果が得られます。各フェーズが他のフェーズとコンテキストウィンドウの容量を取り合うことなく、詳細な分析にウィンドウ全体を使えるためです。

デフォルトの動作：フェーズ 1 のみを実行します。 ユーザーが「quality playbook を実行して」または「quality playbook を実行」と指示した場合は、フェーズ 1（調査）を実行して停止します。フェーズ 1 の完了後、何が行われたかと、次に何を指示すればよいかをユーザーに伝えます。各フェーズを進めるかどうかは、ユーザーが明示的に指定します。

インタラクティブプロトコル — ユーザーへの案内方法

各フェーズと各イテレーションの終了後は、必ず停止して案内を表示してください。 チャットで目立つように、# ヘッダーを使用してください。案内には、直前に行ったこと（1行）、主な出力、および続行するための正確なプロンプトを含めてください。各フェーズのセクションの後に定義されているフェーズ終了時のメッセージを参照してください。

ユーザーが「続けて」「続行」「次のフェーズ」「次へ」など、同様のことを言った場合は、 次のフェーズを順番に実行してください。すべてのフェーズが完了している場合は、最初のイテレーション戦略（gap）を提案してください。イテレーションが終了した直後の場合は、推奨サイクルにおける次の戦略を提案してください。

ユーザーが「すべてのフェーズを実行」「すべて実行」「パイプライン全体を実行」と言った場合は、 1回のセッションですべてのフェーズを順番に実行してください。より多くのコンテキストを使用しますが、これを好むユーザーもいます。

ユーザーが「ヘルプ」「これはどう動きますか」「これは何ですか」など、同様のことを尋ねた場合は、 次の説明を返してください（表現は自然に調整し、文面をそのままコピーしないでください）。

Quality Playbook は、構造的なコードレビューだけでは見つけられないバグを検出します。実際の欠陥のうち35%は、コードが本来どのように動作するべきかを理解する必要があります。Quality Playbook はフェーズごとに動作します。

• フェーズ1（探索）： コードベースを理解します。アーキテクチャ、リスク、障害モード、仕様を調べます。
• フェーズ2（生成）： 要件、テスト、レビュープロトコルなどの品質成果物を作成します。
• フェーズ3（コードレビュー）： 3段階のレビューを実施し、確認済みのバグごとに回帰テストを作成します。
• フェーズ4（仕様監査）： 3つの独立したAI監査者が、要件に照らしてコードを確認します。
• フェーズ5（照合）： バグごとにTDDのレッド・グリーン検証を実施して、対応を完了します。
• フェーズ6（検証）： セルフチェックベンチマークで、生成されたすべての成果物を検証します。

番号付きのフェーズが完了した後、イテレーション戦略（gap、unfiltered、parity、adversarial）を実行して、さらにバグを見つけることができます。イテレーションでは通常、ベースラインから確認済みのバグがさらに40～60%追加で見つかります。

Quality Playbook は、コードと一緒に仕様書、APIドキュメント、設計文書、コミュニティドキュメントなどを提供すると、最も効果を発揮します。また、すべてのフェーズを一度に実行するより、各フェーズを個別に実行すると、結果が大幅に向上します。

開始するには、「このプロジェクトでQuality Playbookを実行してください」 と入力してください。

ユーザーが「何が起きましたか」「今どうなっていますか」「現在どこまで進んでいますか」「次に何をすればよいですか」などと尋ねた場合は、 quality/PROGRESS.md を読み、完了したフェーズ、これまでに見つかったバグの数、次のステップを簡潔に伝えてください。

ドキュメントに関する警告

フェーズ1の開始時に、コードを調査する前にドキュメントを確認してください。 docs/、reference_docs/、doc/、documentation/ という名前のディレクトリや、収集されたドキュメントファイルを探してください。また、ユーザーがプロンプトでドキュメントについて言及していないか確認してください。

ドキュメントが見つからない場合は、次の警告をすぐに表示してください（作業を続ける前に表示します）。

重要：プロジェクトのドキュメントが見つかりません。 Quality Playbook はドキュメントがなくても動作しますが、仕様書、APIドキュメント、設計文書、コミュニティドキュメントがあると、より多くのバグを、より高い確信度で検出できます。管理された実験では、ドキュメントを加えた実行により、コードのみを使ったベースラインとは異なる、より良いバグが見つかりました。

ドキュメントがある場合は、reference_docs/ ディレクトリに追加して、フェーズ1を再実行できます。ドキュメントがない場合は、コードのみを使った分析を続けます。

その後、フェーズ1を実行してください。これを理由に作業を止めず、ユーザーに警告が確実に表示されるようにしてください。

特定のフェーズの実行

ユーザーは任意の個別フェーズを実行するよう依頼できます。

Run quality playbook phase 1.
Run quality playbook phase 3 — code review.
Run phase 5 reconciliation.

特定のフェーズを実行する場合は、前提条件が満たされているか確認してください（たとえば、フェーズ3にはフェーズ2の成果物が必要です）。前提条件が不足している場合は、先に実行する必要があるフェーズをユーザーに伝えてください。

イテレーションモード — 前回の実行結果を改善する

前回のプレイブック実行結果があり、さらにバグを見つけたい場合に使用します。イテレーションモードでは、Phase 1 のゼロからの探索を、5 つの戦略のいずれかを使った対象を絞った探索に置き換えます。その後、前回の実行結果と調査結果を統合し、統合した結果に対して Phases 2–6 を再実行します。

イテレーションモードを使うタイミング： プレイブックを一通り実行した後、最初の実行で見つかった以上にコードベースにバグがあると考えられる場合です。1 回の実行では 3～5 個のサブシステムしか調査できない大規模なコードベースや、探索経路によって異なる種類のバグが見つかるライブラリ／フレームワークのコードベースで、特に効果的です。

戦略の詳しい手順については、references/iteration.md を読んでください。 このファイルには、各戦略の詳細な運用手順、共通ルール、統合手順、完了ゲートが記載されています。以下の概要では、各戦略を使うタイミングを説明します。

イテレーション実行でも TDD が適用されます。 イテレーション実行で新たに確認されたバグはすべて、TDD の red-green サイクルを一通り実施し、quality/results/BUG-NNN.red.log（修正パッチがある場合は .green.log も）を生成する必要があります。品質ゲートではこれが必須となり、ログがない場合は FAIL になります。references/iteration.md の共通ルール 5 と、Phase 5 の TDD ログ完了ゲートを参照してください。

イテレーション戦略。 ユーザーはプロンプトで戦略名を指定します。戦略が指定されていない場合は、既定で gap を使用します。

Run the next iteration of the quality playbook.                          # default: gap strategy
Run the next iteration of the quality playbook using the gap strategy.
Run the next iteration using the unfiltered strategy.
Run the next iteration using the parity strategy.
Run an iteration using the adversarial strategy.

推奨サイクル： gap → unfiltered → parity → adversarial。各戦略で、異なる種類のバグを見つけます。

• gap（既定）— 前回の調査範囲を確認し、未調査のサブシステムや調査が浅い箇所を探索します。最初の実行でコードベースの構造は適切に調査できたものの、一部しか対象にできなかった場合に最適です。
• unfiltered — 構造上の制約を設けず、純粋にドメイン知識に基づいて探索します。パターンテンプレート、適用可能性マトリックス、セクション形式の要件はありません。構造化された探索では見落とされるバグを見つけます。
• parity — 同じ契約を実装する並行した実装（トランスポートのバリエーション、フォールバックチェーン、セットアップとリセットの経路など）を体系的に列挙し、差分を調べて不整合を見つけます。異なる経路を比較することで初めて明らかになるバグを見つけます。
• adversarial — 却下または優先度を下げられたトリアージ結果を再調査し、十分に検証されていない SATISFIED 判定に異議を唱えます。保守的なトリアージによる第二種の過誤を見つけます。
• all — Runner レベルの便利なオプションです。gap → unfiltered → parity → adversarial を、それぞれ別のエージェントセッションとして順番に実行します。新たなバグが 0 件だった戦略があれば、その時点で終了します。

フェーズごとの実行

各フェーズでは、次のフェーズが読み込むファイルをディスク上に作成します。フェーズ間でコンテキストを引き継ぐ方法は、会話履歴ではなくファイルを介することです。主な引き継ぎファイルは次のとおりです。

• quality/EXPLORATION.md — フェーズ1で作成し、フェーズ2で読み込みます。コードベースを再調査せずに成果物を生成するために、フェーズ2が必要とするすべての情報を含みます。
• quality/PROGRESS.md — 各フェーズの完了後に更新します。累積的な BUG トラッカーにより、調査結果が失われないようにします。
• 生成された成果物（REQUIREMENTS.md、CONTRACTS.md など）— フェーズ2で作成し、フェーズ3〜5でレビュー、監査、調整に使用します。

各フェーズの境界では、現在のフェーズを完了してすべてをディスクに書き込み、その後、フェーズ終了メッセージを出力して停止します。ユーザーが次のフェーズを開始したら、続行する前に必要なファイルを読み戻します。この「書き込んでから読み込む」サイクルがフェーズの境界となり、たとえばレビューのコンテキストを読み込む前に、調査時のコンテキストを作業メモリから解放できます。

続行する前に、フェーズ1の調査結果を quality/EXPLORATION.md に書き込んでください。このファイルは、すべてのモードで必須です。内容は十分に詳細にしてください。対象ドメインの特定、アーキテクチャマップ、既存のテスト、仕様の概要、品質リスク、スケルトン／ディスパッチの分析、導出された要件（REQ-NNN）、導出されたユースケース（UC-NN）を含めてください。成果物の生成にフェーズ2が必要とする情報をすべて、このファイルに記載してください。

調査結果をディスクに書き出すという規律によって、徹底的な分析が促されます。これを行わないと、モデルは曖昧な印象を作業メモリに留めたまま、関数レベルの不具合を見落とす広範で抽象的な要件を生成しがちです。書き出すことで具体性が求められます。ファイルパス、行番号、正確な関数名、具体的な動作規則を記載します。この具体性によって、コードレビュー中にバグを検出できる精度の高い要件になります。

---

実行状態の計測（v1.5.6 — イベントを随時記録）

quality/ 内の2つのファイルで、ファイルシステムを通じてこの実行の状態を追跡します。これにより、実行中の状況を把握し、クラッシュ後に再開でき、実行後に監査できます。実行中は、両方のファイルを維持してください。

• quality/run_state.jsonl — 追記専用の機械可読イベントログです。1行につき1つの JSON オブジェクトを記録します。オーケストレーターやモニターはこのファイルを読み、実行がどこまで進んでいるかを正確に把握します。
• quality/PROGRESS.md — 人間が読めるステータスファイルです。各イベントのたびにアトミックに書き換えます。

正規のスキーマ： references/run_state_schema.md。実行開始時に一度読み込んでください。イベント分類、必須フィールド、相互検証ルール、PROGRESS.md の形式がすべて定義されています。

初期化（フェーズ0を含む、あらゆるフェーズの作業を開始する前）

quality/run_state.jsonl が存在しない場合：

1. quality/ が存在しない場合は作成します。
2. _index イベントを quality/run_state.jsonl に追記します。必須フィールド：event=_index、ts（Z 付き ISO 8601 UTC）、schema_version="1.5.6"、event_types（この実行で使用するすべてのイベントタイプを列挙した配列。最低限、_index、run_start、phase_start、pattern_walked、pass_started、pass_ended、finding_logged、artifact_written、gate_check、phase_end、error、run_end を含めます）、benchmark（対象名）、lever_state（通常の実行では例として "baseline"）、started_at。
3. run_start イベントを追記します。必須フィールド：event=run_start、ts、runner（claude／codex／copilot／cursor のいずれか）、playbook_version（SKILL.md の frontmatter にある version フィールドから読み込みます）、target_path。
4. references/run_state_schema.md の形式仕様に従って quality/PROGRESS.md を書き込みます。ヘッダー（Started／Benchmark／Lever／Runner／Playbook version）、6つすべてのフェーズを含む未チェックのフェーズチェックリスト、空の Recent events セクションと Artifacts produced セクションを記載します。

実行開始時に quality/run_state.jsonl がすでに存在する場合：これは再開された実行です。以下の「再開のセマンティクス」を参照してください。

フェーズごとのイベント

フェーズ境界（1〜6）のたびに、次のイベントを記録します。

• フェーズ開始時： quality/run_state.jsonl に {"event":"phase_start","ts":"<now>","phase":N} を追記します。quality/PROGRESS.md を更新し、フェーズ N を現在のタイムスタンプ付きで進行中にします。
• フェーズ終了時： まず、該当フェーズで必要な成果物（下表）を相互検証します。検証に失敗した場合は、{"event":"error","ts":"<now>","phase":N,"message":"<what's missing>","recoverable":true} を追記して、そのフェーズを再実行します。検証に合格した場合は、{"event":"phase_end","ts":"<now>","phase":N,"key_counts":{...},"artifacts_produced":[...]} を追記します。PROGRESS.md を更新し、要約統計とともにフェーズ N にチェックを付けます。

フェーズ 1 のサブイベント（phase_start／phase_end に加えて）：

• 7 つの探索パターンそれぞれを確認した後、{"event":"pattern_walked","ts":"<now>","phase":1,"pattern":N,"findings_count":K} を追記します（各パターンにつき 1 イベント。該当事項がゼロの場合も記録します）。
• quality/EXPLORATION.md を書き込んだとき、{"event":"artifact_written","ts":"<now>","relative_path":"quality/EXPLORATION.md","byte_size":<size>,"line_count":<lines>} を追記します。

フェーズ 4 のサブイベント：

• 各パスの開始時（A〜D）：{"event":"pass_started","ts":"<now>","phase":4,"pass":"A"}。
• 各パスの終了時：{"event":"pass_ended","ts":"<now>","phase":4,"pass":"A","output_artifact":"<path>"}。

フェーズ 5／フェーズ 6 のサブイベント：

• 各ゲートチェックの完了時：{"event":"gate_check","ts":"<now>","gate_name":"<name>","verdict":"pass|fail|warn|skip","reason":"<short>"}。

実行終了時：

• フェーズ 6 の phase_end の後に、{"event":"run_end","ts":"<now>","status":"success","total_findings":<N>,"final_verdict":"<gate verdict>"} を追記します。recoverable:false の失敗時はステータスを aborted、回復不能な実行時エラーの場合は failed にします。

phase_end 時の相互検証ルール

各 phase_end イベントを書き込む前に、対応する成果物を検証します。

フェーズ	必須要件
1	quality/EXPLORATION.md と quality/PROGRESS.md が、SKILL.md:1257-1273 に記載されたフェーズ 1 の 13 項目のゲートを満たしていること（必須見出し 6 つ：## Open Exploration Findings、## Quality Risks、## Pattern Applicability Matrix、## Pattern Deep Dive — * ×3 以上、## Candidate Bugs for Phase 2、## Gate Self-Check。PROGRESS のフェーズ 1 の行に [x] が付いていること。file:line 形式の引用付きの所見が 8 件以上あること。複数箇所にまたがる所見が 3 件以上あること。FULL パターンのマトリクス行が 3〜4 件あること。複数関数にまたがるパターンの詳細な分析が 2 件以上あること。候補バグの情報源の内訳が、探索／リスクから 2 件以上、かつパターン詳細分析から 1 件以上であること）。bin/run_state_lib.validate_phase_artifacts(quality_dir, phase=1) がゲート全体を検証します。
2	Generate コントラクトの成果物 9 点すべてが quality/ に存在し、内容が空でないこと：REQUIREMENTS.md、QUALITY.md、CONTRACTS.md、COVERAGE_MATRIX.md、COMPLETENESS_REPORT.md、RUN_CODE_REVIEW.md、RUN_INTEGRATION_TESTS.md、RUN_SPEC_AUDIT.md、RUN_TDD_TESTS.md。さらに、空でない quality/test_functional.<ext> が少なくとも 1 つ存在すること（拡張子は言語によって異なります）。
3	quality/RUN_CODE_REVIEW.md が存在すること
4	quality/REQUIREMENTS.md の内容が空でなく、quality/COVERAGE_MATRIX.md が存在すること。4 パスのスキル導出パイプラインを実行した場合（つまり quality/phase3/ が存在する場合）、quality/phase3/pass_a_drafts.jsonl、quality/phase3/pass_b_citations.jsonl、quality/phase3/pass_c_formal.jsonl、および quality/phase3/ 内の Pass D inbox がすべて存在し、内容が空でないこと。
5	quality/results/quality-gate.log が存在し、内容が空でないこと
6	quality/BUGS.md の内容が空でなく、^##\s+BUG- に一致するセクションを含み、quality/INDEX.md が gate_verdict フィールドで更新されていること

チェックに失敗した場合は、error イベント（recoverable=true）を追記して、そのフェーズを再実行します。成果物が欠けた状態で phase_end を書き込んではいけません。これは v1.5.6 で検出できるようにした失敗パターンです。

bin/run_state_lib.validate_phase_artifacts(quality_dir, phase) がこれらのチェックをプログラムで実行します。利用可能な場合は、プレイブックのセッション内から呼び出してください。

再開時のセマンティクス

プレイブックの開始時に quality/run_state.jsonl がすでに存在する場合（前のセッションが実行途中でクラッシュまたは一時停止した場合）：

1. すべてのイベントを読み込みます。bin/run_state_lib.last_in_progress_phase(events) を使って、対応する phase_end が続いていない最後の phase_start を特定します。これを実行中のフェーズとします。
2. そのフェーズに対して、上記の相互検証ルールを実行します。
   • 成果物が完成している場合： 前のセッションでは作業を終えていましたが、phase_end の書き込みまで至っていません。不足している phase_end（現在の ts を含む）を追記し、次のフェーズに進みます。
   • 成果物が未完成の場合： そのフェーズを最初から再実行します。
3. 6 つすべての phase_end イベントが存在し、run_end がない場合は、run_end status=success を追記して終了します。
4. quality/run_state.jsonl が存在しない場合は、新規実行です。上記のセクションに従って初期化します。

方針：イベントより成果物を信頼します。 イベントではフェーズ 4 が完了したことになっていても、REQUIREMENTS.md が存在しない場合はフェーズ 4 を再実行します。イベントがフェーズの途中で終わっていても、成果物が完成している場合はイベントを補完します。

PROGRESS.md のアトミックな書き換え

PROGRESS.md はイベントごとに書き換えます（追記ではありません）。内容は現在の run_state.jsonl を反映します。ヘッダー（実行メタデータ）、フェーズチェックリスト（完了したフェーズの概要統計と、現在のフェーズの進行中マーカーを含む）、最近のイベント（JSONL ログの最後の 10 件を人間が読める形式で表示）、生成された成果物（この実行で書き込まれたファイルとそのバイトサイズ）を記載します。正確なフォーマットのテンプレートについては references/run_state_schema.md を参照してください。

bin/run_state_lib.write_progress_md(quality_dir, events, current_phase) はイベント一覧から適切な形式の PROGRESS.md を生成します。ファイルの内容を同期させるため、各イベントの後に呼び出してください。

---

フェーズ 0：前回実行の分析（自動）

このフェーズは、quality/previous_runs/ が存在し、過去の品質成果物が含まれている場合にのみ実行されます。 過去の実行がない場合は、フェーズ 1 に進んでください。quality/previous_runs/ が存在しても空である場合、または適合する品質成果物（その中に quality/BUGS.md があるサブディレクトリ）が含まれていない場合は、フェーズ 0a をスキップしてフェーズ 0b に進んでください。（v1.5.4 より前の quality/runs/ にあるレガシーアーカイブも後方互換性のために読み取り可能です。詳しくは SKILL.md:149 を参照してください。ただし、正式なアーカイブルートは quality/previous_runs/ です。）

過去の実行がある場合、プレイブックは継続モードに入ります。これにより、バグを反復的に発見できます。各実行では、過去の実行で確認された問題を引き継いで機械的に検証し、さらにバグがないか調査します。新たに発見されたバグが 0 件となった時点で、反復は収束します。

ステップ 0a：シードリストを作成します。 過去のすべての実行から quality/previous_runs/*/quality/BUGS.md を読み取ります。確認済みの各バグについて、バグ ID、ファイルと行番号、概要、回帰テストのアサーションを抽出します。ファイルと行番号を基準に重複を排除します（複数の実行で見つかった同一のバグは 1 件として数えます）。次の形式で、統合したシードリストを quality/SEED_CHECKS.md に書き込みます。

## Seed Checks (from N prior runs)

| Seed | Origin Run | File:Line | Summary | Assertion |
|------|-----------|-----------|---------|-----------|
| SEED-001 | run-1 | virtio_ring.c:3509-3529 | RING_RESET dropped | `"case VIRTIO_F_RING_RESET:" in func` |

ステップ 0b：シードチェックを機械的に実行します。 各シードについて、現在のソースツリーに対してアサーションを実行します。PASS（前回の実行以降にバグが修正された）または FAIL（バグがまだ存在する）を記録します。FAIL となったシードは引き継ぎ対象の確認済みバグです。監査担当者が独自に見つけたかどうかにかかわらず、今回の実行の BUGS.md に必ず記載してください。PASS となったシードはバグが修正済みであることを意味します。PROGRESS.md に「SEED-NNN：前回の実行以降に解決済み」と記録してください。

ステップ 0c：前回の実行範囲を特定します。 過去の実行から quality/previous_runs/*/quality/PROGRESS.md を読み取り、範囲の宣言を確認します。過去の実行で対象となったサブシステムを記録してください。フェーズ 1 の調査では、新しいバグを見つける可能性を最大化するため、過去の実行で対象にならなかった領域を優先してください。すべてのサブシステムが過去の実行で対象になっている場合は、重点を変え（例：別の精査領域、別のエントリーポイント）、同じ範囲を調査してください。

ステップ 0d：後続フェーズにシードを引き継ぎます。 シードリストを次の項目への入力として使用します。

• フェーズ 3（コードレビュー）： コードレビューのプロンプトに次を追加します。「前回の実行でこれらのバグが確認されています。現在も存在するか検証し、同じサブシステムでほかの問題も探してください。」
• フェーズ 4（仕様監査）： RUN_SPEC_AUDIT.md に次を追加します。「前回の実行で判明した未解決の問題：[シードリスト]。監査担当者がこれらを見つけることを想定してください。監査担当者が既知のシードバグを指摘しなかった場合、それはレビューのカバレッジ不足であり、バグが修正された証拠ではありません。」

これが必要な理由： 調査範囲が非決定的なため、実行ごとに異なるバグが見つかることがあります。バージョンをまたいだテストでは、8 つのリポジトリのうち 4 つで、バグが修正されていないにもかかわらず、モデルがコードベースの異なる箇所を調査したため、一部のバージョンでは見つかり、ほかのバージョンでは見つからないという結果になりました。シードを引き継いで反復することで、この問題を解決できます。確認済みのバグは機械的に引き継がれるため、再発見する必要はありません。また、新しい実行では未調査の領域に重点を置くことができます。

Phase 0b: サイブラン・シード発見（自動）

このステップは、quality/previous_runs/ が存在しない場合、または quality/previous_runs/ が存在しても適合する品質アーティファクトを含まない場合（つまり、Phase 0a で扱えるものがない場合）かつ プロジェクトディレクトリがバージョン管理されている場合（例：httpx-1.3.23/ が httpx-1.3.21/ と並んで存在する場合）にのみ実行されます。quality/previous_runs/ に適合する成果物が存在する場合、シードの注入は Phase 0a がすでに処理するため、このステップはスキップしてください。

quality/previous_runs/ は存在するが空である、または適合しないサブディレクトリのみを含む場合は、警告を出力してください：「Phase 0b: quality/previous_runs/ は存在しますが、適合する成果物が含まれていません。シードを得るために兄弟のバージョン付きディレクトリを参照します。」その後、以下の兄弟ディレクトリの発見を続行します。

quality/previous_runs/ ディレクトリが存在せず、兄弟のバージョン付きディレクトリが存在する場合は、それらの兄弟から過去の品質成果物を探してください：

1. 兄弟を発見する。 親ディレクトリを基準に、パターン <project-name>-<version>/quality/BUGS.md に一致するディレクトリを列挙します。現在のディレクトリは除外します。バージョンの降順（最新のものが先頭）でソートします。
2. 確認済みバグをシードとして取り込む。 quality/BUGS.md を持つ兄弟ごとに、Step 0a と同じ形式で確認済みバグを抽出します。それらを quality/SEED_CHECKS.md に書き出し、起源として兄弟ディレクトリ名を記載します。
3. シードチェックを機械的に実行する（Phase 0a の Step 0b と同じ）。取り込んだシードごとに、現在のソースツリーに対してアサーションを実行し、PASS/FAIL を記録します。
4. 後続フェーズへ注入する（Phase 0a の Step 0d と同じ）。

このステップが存在する理由： v1.3.23 のベンチマークでは、httpx-1.3.21 が Headers.__setitem__ の非 ASCII エンコーディングのバグを発見していたにもかかわらず、httpx はバグゼロの結果を出しました。モデルは単に別のコードパスを探索し、Headers の領域を一度も調べなかったのです。兄弟ディレクトリからのシードにより、明示的な quality/previous_runs/ アーカイブがなくても、過去のバージョン付き実行で確認されたバグが引き継がれることが保証されます。これは機械的な改ざんとは異なる失敗クラスであり、証拠の破損ではなく、探索の非決定性に対処するものです。

---

Phase 1: コードベースの探索（進めながら記録する）

v1.5.6 計装： 今すぐ quality/run_state.jsonl に phase_start phase=1 を追記してください。各探索パターンを走査した後は、pattern_walked phase=1 pattern=N findings_count=K を追記します。フェーズ終了時には相互検証を行い（quality/EXPLORATION.md が200バイト以上で、発見事項のセクションを含むこと）、その後 phase_end phase=1 を追記します。上記の「Run-state 計装」を参照してください。

このフェーズで必要な参照資料 — 進む前に以下を読んでください：

• references/exploration_patterns.md — 自由探索の後に適用する7つのバグ発見パターン

最初のアクション：実行メタデータを作成する。 探索の前に、実行メタデータファイルを作成します：

mkdir -p quality/results
cat > "quality/results/run-$(date -u +%Y-%m-%dT%H-%M-%S).json" <<'METADATA'
{
  "schema_version": "1.0",
  "skill_version": "1.5.6",
  "project": "<repo-name>",
  "model": "<model-string>",
  "model_provider": "<provider>",
  "runner": "<tool>",
  "start_time": "<ISO-8601-UTC>",
  "end_time": null,
  "duration_minutes": null,
  "phases_completed": [],
  "iterations_completed": [],
  "bug_count": 0,
  "bug_severity": { "HIGH": 0, "MEDIUM": 0, "LOW": 0 },
  "gate_result": null,
  "gate_fail_count": null,
  "gate_warn_count": null,
  "notes": ""
}
METADATA

project、model（正確なモデル文字列。例："claude-sonnet-4-6"）、model_provider（例："anthropic"、"openai"、"cursor"）、runner（例："claude-code"、"copilot-cli"、"cursor"）、start_time（UTC の ISO 8601 形式）を記入してください。各フェーズの終了時にこのファイルを更新し、完了したフェーズを phases_completed に追記し、バグが確認されるたびに bug_count/bug_severity を更新します。終端ゲートの後の最終更新で、end_time、duration_minutes、gate_result を記入します。

2番目のアクション：v1.5.3 ドキュメント取り込みを実行する（コードを探索する前に）。 bin/ にある標準ライブラリのみで動作する単一のモジュールが、Phase 1 の要件導出が依存する正式なドキュメント記録を生成します：

1. python -m bin.reference_docs_ingest <target> — 対象リポジトリの reference_docs/ を一度走査します。reference_docs/cite/ 配下のファイルはハッシュ化され、schemas.md §4 および §1.6 のマニフェストラッパーに従って quality/formal_docs_manifest.json に書き出されます。reference_docs/ 直下のファイルはマニフェストには書き出されませんが、bin.reference_docs_ingest.load_tier4_context(<target>) を通じて Tier 4 コンテキストとして利用できます。この関数は (path, text) タプルをソートしたリストを返します。ingest コマンドが失敗した場合（未対応の拡張子、UTF-8 以外のバイト列など）は、実行を停止し、stderr の出力をそのままユーザーに提示してください。ingest のエラーは対処可能な問題であり、探索を続ける前に修正する必要があります。

サイドカーファイルは不要です。 フォルダの配置がフラグの役割を果たします。reference_docs/<name>.<ext> の直下にあるファイルは Tier 4 コンテキストであり、reference_docs/cite/<name>.<ext> のファイルは引用可能なソースです。cite/ 配下の内容はデフォルトで Tier 1 となります。ファイルは、先頭の空でない行に任意のファイル内マーカーを置くことで Tier 2 に変更できます。マーカーは Markdown の場合は `` 、プレーンテキストの場合は # qpb-tier: 2 です。どちらのフォルダ配下にある README.md もスキップされます。

reference_docs/ が存在しない、または空の場合、Phase 1 では次の対処可能なメッセージを必ず表示し、処理を続行しなければなりません:

Phase 1 found no documentation in reference_docs/. The playbook will proceed using only Tier 3 evidence (the source tree itself). For better results, drop plaintext documentation into: reference_docs/ ← AI chats, design notes, retrospectives (Tier 4 context) reference_docs/cite/ ← project specs, RFCs, API contracts (citable, byte-verified) See README.md "Step 1: Provide documentation" for details.

プレーンテキストのみ対応。変換はプレイブックの外で行います。 参考ドキュメントは .txt または .md のみです（schemas.md §2）。PDF、DOCX、HTML などは、変換方法のヒント（pdftotext、pandoc -t plain、lynx -dump）とともに拒否されます。スキル内でバイナリや書式付きドキュメントを解析しようとしないでください。変換はプレイブックの外で実行し、プレーンテキストをコミットしてください。

最初のフェーズは、プロジェクトを理解することに充ててください。品質プレイブックは、一般論ではなく、この特定のコードベースに基づいたものでなければなりません。

なぜ最初に探索するのか？ AI が生成する品質プレイブックで最もよくある失敗は、汎用的な内容を生み出すことです。どのプロジェクトにも当てはまるカバレッジ目標、理論上の失敗を描いたシナリオ、プロジェクトのコードではなく言語の組み込み機能を検証するテストなどが例です。探索は、すべての成果物が実在するものを参照することを強制することで、この問題を防ぎます。具体的な関数、具体的なスキーマ、具体的な防御的コードパターンなどです。コード内のどこにあるかを示せないのであれば、それは推測であり、推測から生まれた品質プレイブックは誰からも信頼されません。

大規模なコードベースへの対応: ソースファイルが約 50 を超えるプロジェクトでは、すべてを読もうとしないでください。主要なデータフローを扱うモジュール、最も複雑なロジック、最も失敗しやすい操作を担う、3〜5 個の中核モジュールに探索を絞ってください。各サブシステムからは、すべてのテストファイルではなく、代表的なテストを読んでください。目指すのは、すべてを広く見ることではなく、重要な部分を深く掘り下げることです。

広さより深さ（極めて重要）。 対象範囲を狭くして関数レベルの詳細を押さえるほうが、対象範囲を広くしてサブシステム単位の要約にとどめるより多くのバグを発見できます。探索する中核モジュールごとに、重要な振る舞いを実装している具体的な関数を特定し、名前、ファイルパス、行番号で文書化してください。「リセットサブシステムはエラーを処理すべきである」という要件からはバグを見つけられません。「virtio_mmio.c:256 の vm_reset() は、ゼロを書き込んだ後にステータスレジスタをポーリングしなければならない」という要件からは見つけられます。有用な探索とそうでない探索の違いは具体性にあります。ファイルパス、関数名、行番号、正確な振る舞いの規則を示してください。

3 段階の探索: 最初に全体を把握し、次にドメインのリスクを洗い出し、最後に選択したパターンを調べます。 探索は 3 つの段階からなり、その順序が重要です:

1. オープンな探索（ドメイン主導）。 構造化されたパターンを適用する前に、経験豊富な開発者と同じようにコードベースを探索します。コードを読み、アーキテクチャを理解し、この種のシステムで何が問題になるかについてのドメイン知識に基づいて、リスクを特定します。「このドメインのエキスパートなら、まず何を確認するだろう？」と自問してください。HTTP ライブラリなら、リダイレクト処理、ヘッダーのエンコーディング、接続のライフサイクルが対象です。CLI フレームワークなら、フラグの解析、ヘルプの生成、補完と検証の一貫性が対象です。シリアライゼーションライブラリなら、型の網羅性、往復変換の忠実度、エッジケースへの対応が対象です。ファイルパスと行番号を添えて、具体的な発見事項を書き出してください。この段階では、具体的なバグの仮説または疑わしい点を少なくとも 8 件挙げる必要があります。アーキテクチャに関する所見ではなく、「[理由] により、ファイル:行のこのコードは誤っている可能性がある」という具体的な指摘にしてください。少なくとも 4 件は、異なるモジュールまたはサブシステムに言及してください。

2. ドメイン知識に基づくリスク分析。 オープンな探索の後、コードから離れて、学習を通じて得た、この種のシステムに関する知識をもとに考察します。これは、ライブラリやフレームワークのコードベースを対象とした、主要なバグ探索の段階です。コードの探索結果と、類似システムに関するドメイン知識の 2 つを使って、以下のステップ 6 の質問に答えてください。具体的な失敗シナリオを少なくとも 5 件、順位を付けて挙げ、それぞれについて具体的な関数、ファイル、行を示し、ドメイン固有のエッジケースがどのように誤動作を引き起こすかを説明してください。実際にこれらの不具合を確認している必要はありません。この種のシステムでは発生することを、学習を通じて知っているはずです。パターン分析に進む前に、結果を EXPLORATION.md の ## Quality Risks セクションに書き込んでください。

   この段階で作成してはならないもの： コードにすでに存在する防御的なパターン（コードが適切に行っていること）を列挙するセクションは、リスク分析ではありません。具体的な失敗シナリオを示さずに、リスクのあるモジュールを列挙するセクションも、リスク分析ではありません。「成熟した、十分にテストされたライブラリなので、基本的なバグは起きにくい」と結論付けるセクションは、むしろ有害です。成熟したライブラリには、明白な問題が何年も前に見つかっているからこそ、最も見つけにくいバグが潜んでいます。判断基準は、コードレビュー担当者が各シナリオを読んですぐに確認箇所を把握できるかどうかです。できない場合、そのシナリオは抽象的すぎます。

3. パターン主導の探索（選択式、網羅的ではありません）。 オープンな探索とドメインリスク分析をディスクに書き込んだ後、パターン適用性マトリックスを使って exploration_patterns.md の 7 つの分析パターンすべてを評価します。各パターンについて、このコードベースに適用できるか、何を対象とするかを評価してください。そのうえで、このコードベースに最も有効なパターンを 3～4 個選び、詳細に調査します。残りのパターンには、コードベース固有の根拠を添えて、「該当なし」または「保留」の簡潔な注記を付けます。7 つすべてについて詳細なセクションを作成しないでください。7 つを浅く網羅するより、3～4 個を深く掘り下げる方が効果的です。4 つ目のパターンに明確な適用可能性があり、他の 3 つでは扱わないコード領域をカバーできる場合は 4 つ選び、判断に迷う場合は 3 つを標準としてください。

   選択した各パターンの詳細調査では、参照ファイルにある出力形式に従い、2 つ以上の関数をまたいでコードパスを追跡してください。詳細調査では、オープンな探索やリスク分析の発見事項を圧力テストし、精査または拡張してください。繰り返すだけではいけません。

Phase 1 の完了ゲートでは、3 つの段階すべてが完了していることを確認します。オープンな探索のセクション、品質リスクのセクション、パターン適用性マトリックス、パターンの詳細調査セクションがすべて含まれている必要があります。

段階的に書き込んでください。発見事項をメモリに留めてはいけません。 これが Phase 1 で最も重要な実行ルールです。サブシステムの探索または各パターンの適用が終わったら、次のサブシステムまたはパターンに進む前に、発見事項をすぐにディスク上の quality/EXPLORATION.md に追記してください。 複数のサブシステムにまたがる発見事項を作業メモリに保持しようとしてはいけません。作業しながら書き込む習慣には、次の 2 つの目的があります。

1. 深度の回復。 PCI 割り込みルーティングサブシステムを調査していて、vp_find_vqs_intx() に疑わしいコードを見つけたら、その発見をすぐに EXPLORATION.md に書き込みます。その後、管理キューサブシステムに移れば、作業メモリをそちらの深い調査に使えます。段階的に書き込まなければ、最初のサブシステムの発見が2番目のサブシステムの発見と競合し、どちらも浅い内容になってしまいます。

2. 何も失われません。 v1.3.41 のベンチマークでは、モデルは8つのパターンセクションを調査しましたが、各セクションに書き込んだのは5～7行だけで、ばらつきのない、完全に浅い内容でした。すべてのセクションがゲートを通過しましたが、複数の関数をまたいでコードパスを追跡しなければ見つからないバグを発見できるほど、深く掘り下げたセクションはありませんでした。モデルはすべてを読み終えた後で EXPLORATION.md 全体をまとめようとしていたため、表面的な発見しか思い出せませんでした。段階的に書き込めば、これを防げます。

基本のリズムは、サブシステムを読む → 発見事項をディスクに書き込む → 次のサブシステムを読む → 発見事項を追記する → これを繰り返す、です。 追記する内容には、具体的な関数名、ファイルパス、行番号、具体的なバグ仮説を含めてください。「実装間の一貫性を確認し、1つの不整合を発見した」とだけ書かれた5行のセクションは、ゲートを通過するための仮置きであり、調査結果ではありません。有用なセクションではコードパスをたどります。たとえば、「file:line にある関数 A は file:line にある関数 B を呼び出し、B は X を実行するが Y は実行しません。これに対し、file:line にある関数 C は X と Y の両方を実行します」のように記述します。

統合の必須手順。 3つの段階（オープン調査、品質リスク、選択したパターンの詳細調査）をすべて調査して EXPLORATION.md に書き込んだ後、最後に ## Candidate Bugs for Phase 2 セクションを追加します。このセクションでは、前のすべてのセクションから有力なバグ仮説を集約し、優先順位を付けた引き継ぎリストを作成します。各候補には、仮説、具体的な file:line の参照、発見された段階（オープン調査、品質リスク、パターン）、コードレビューで確認すべき点を含めてください。このセクションは調査から成果物作成への橋渡しとなり、Phase 3 に調査の焦点を伝えます。最低でも、file:line の参照を含むバグ候補を4つ記載してください。そのうち少なくとも2つはオープン調査または品質リスクから、少なくとも1つはパターンの詳細調査から選んでください。上限はありません。

事前確認：大規模リポジトリのスコープ宣言

ソースコードを調査する前に、規模を見積もります。テスト、ドキュメント、生成ファイルを除いたソースファイルのおおよその数、主要なサブシステムの数、ドキュメントの量を確認してください。その件数を PROGRESS.md に記録します。

• ソースファイルが200個未満の場合： 全体を調査します。上記の深さと広さに関する指針は引き続き適用されます。
• ソースファイルが200～500個の場合： 調査前に、予定するスコープを明示します。PROGRESS.md に ## Scope declaration セクションを作成し、対象とする3～5個のサブシステム、各サブシステムで見込まれるファイル数、後回しにするサブシステムとその理由を記載してください。その後、宣言したスコープのみを調査します。
• ソースファイルが500個を超える場合： ソースファイルを読む前に調査を中止し、必須のスコープ宣言を PROGRESS.md に記載します。スコープ宣言には、(a) 今回の実行で対象とするサブシステム、(b) 明示的に後回しにするサブシステム、(c) 後回しにする各サブシステムを除外する理由、(d) 後続の実行で推奨するサブシステムのスコープを含めてください。これを書き込むまでは調査を始めないでください。この基準を超えるリポジトリで「すべて」を対象とするスコープ宣言は認められません。

前のセッションから再開する場合： PROGRESS.md がすでに存在し、フェーズが完了済みと記されている場合は、まずそれを読みます。完了済みのフェーズはやり直さず、最初の未完了フェーズから再開してください。スコープ宣言がすでに記載されている場合は、必ずそれに従ってください。前のセッションのスコープ宣言でサブシステムが後回しにされていた場合、今回の実行がそれらの領域を対象とする後続実行であると明示されていない限り、スコープを広げてそれらを対象にしないでください。 仕様書が主となるリポジトリ： 仕様書、設定、またはプロトコル文書を主な成果物として提供し、実行可能なコードはそれを支える基盤として扱うリポジトリもあります。例としては、ベンチマーク用ツールを備えたスキル定義、検証スクリプトを備えたスキーマレジストリ、オーケストレーション用ヘルパーを備えたパイプライン設定などが挙げられます。主な成果物が実行可能なコードではなく仕様書である場合、要件は実行可能なコードパスだけでなく、仕様書の内部整合性、完全性、正確性に基づいて導き出してください。ユーザーが依存するのは仕様書であり、ツールは二次的なものです。要件の80％以上をヘルパースクリプトについて書き、主な仕様書については20％未満しか書いていない場合、焦点が逆になっています。

ステップ 0：開発履歴について尋ねる

コードを調べる前に、ユーザーに次の質問を1つしてください。

「このプロジェクトの開発中に作成したAIチャット履歴をエクスポートしたものはありますか？Claudeのエクスポート、Geminiのテイクアウト、ChatGPTのエクスポート、Claude Codeのトランスクリプトなどが該当します。ある場合は、そのフォルダーを教えてください。そうしたチャットに含まれる設計上の議論、インシデント報告、品質に関する判断があると、生成される品質プレイブックの質を大幅に高められます。」

ユーザーがチャット履歴のフォルダーを提供した場合：

1. まずインデックスファイルを探してください。 INDEX*、CONTEXT.md、README.mdなど、ナビゲーション用のファイルを探します。見つかったら、それを読み、内容と情報の探し方を確認してください。
2. 品質に関連する会話を検索してください。 quality、testing、coverage、bugs、failures、incidents、crashes、validation、retry、recovery、spec、fitness、audit、reviewに言及するメッセージを探します。プロジェクト名も検索してください。
3. 設計上の判断とインシデント履歴を抽出してください。 特に価値の高い情報は次のとおりです。（a）インシデント報告 — 何が問題だったか、影響を受けたレコード数、問題がどのように検出されたか。（b）設計上の議論 — 特定のアプローチを選んだ理由、却下した代替案。（c）品質フレームワークに関する議論 — カバレッジ目標、テストの考え方、モデルレビューの経験。（d）複数モデルからのフィードバック — コードについて異なるAIモデルの意見が食い違った点。
4. すべてを読もうとしないでください。 チャット履歴は膨大な場合があります。インデックスから関連性の高い会話を見つけ、その中で品質関連の内容を検索してください。10分間の的を絞った検索のほうが、2時間かけてすべて読むより効果的です。

このコンテキストは非常に貴重です。開発者が「なぜこの並行処理モデルを選んだのか」や「本番環境で1,693件のレコードを失ったときのこと」を議論したチャット履歴があれば、一般的なシナリオを信頼性の高いものに変えられます。

チャット履歴がない場合は、通常どおり進めてください。このスキルは履歴がなくても機能しますが、利用できるコンテキストは少なくなります。

自律実行時の代替手順： ベンチマークモードでの実行時、bin/run_playbook.py経由（このベンチマークランナーはスキルには同梱されていません）の実行時、またはユーザーとのやり取りがない場合（例：--single-pass）は、ステップ0の質問を省略して、ステップ1に進んでください。プロジェクトツリー内にチャット履歴のフォルダー（例：AI Chat History/、.chat_exports/）が見える場合は、質問せずに確認してください。チャット履歴が見つからなくても、そのまま進めてください。返答が得られないのに待機して処理を止めてはいけません。

ステップ 1：ドメイン、技術スタック、仕様を特定する

README、既存のドキュメント、ビルド設定（pyproject.toml / package.json / Cargo.toml）を読み、次の質問に答えてください。

• このプロジェクトは何をするものですか？（1 文で）
• 使用言語と主な依存関係は何ですか？
• どの外部システムと通信しますか？
• 主な出力は何ですか？

仕様を見つけてください。 仕様は、機能テストの信頼できる情報源です。次の順に検索してください。ルートディレクトリの AGENTS.md / CLAUDE.md、specs/、docs/、spec/、design/、architecture/、adr/、続いてルートディレクトリの .md ファイルです。見つかったファイルのパスを記録してください。

正式な仕様書が存在しない場合でも、このスキルは機能しますが、他の情報源から要件をまとめる必要があります。優先順位は次のとおりです。

1. ユーザーに尋ねる — 要件が文書化されていなくても、ユーザーが把握していることはよくあります。
2. README とインラインドキュメント — 多くのプロジェクトでは、README、API ドキュメント、コードコメントに要件が記載されています。
3. 既存のテストスイート — テストは暗黙の仕様です。たとえば、テストで process(x) == y がアサートされていれば、それは要件です。
4. 型シグネチャと検証ルール — スキーマ、型注釈、バリデーターによって、システムが受け入れるものと拒否するものが定義されています。
5. コードの動作から推測する — 最終手段としてコードを読み、想定される動作を推測します。これらは QUALITY.md で推測された要件として記載し、ユーザーの確認が必要であることを明示してください。

正式でない要件に基づいて作業する場合は、各シナリオとテストに、信頼度と情報源を含む要件タグを付けてください。

• [Req: formal — README §3] — 仕様書に人が記載した要件です。正式な根拠として扱います。
• [Req: user-confirmed — "must handle empty input"] — ユーザーが述べた要件ですが、正式な文書には記載されていません。正式な根拠として扱います。
• [Req: inferred — from validate_input() behavior] — コードから推測した要件です。ユーザーによる確認が必要であることを明示してください。

QUALITY.md のシナリオ、機能テストのドキュメント、仕様監査の指摘には、この正確なタグ形式を使用してください。これにより、正式な根拠がある要件と、検証が必要な要件を明確に区別できます。

ステップ 1b：ドキュメントの深さを評価する

reference_docs/ が存在する場合、注力するサブシステムを決める前に、その中のすべてのファイルを読みます。各ドキュメントの深さを分類します。

• 詳細 — 内部契約、安全性の不変条件、並行処理モデル、防御的パターン、エラー処理の詳細、または行番号レベルのソース参照が記載されています。要件の導出に適しています。
• 中程度 — アーキテクチャと API の概要に加え、実装の詳細も一部記載されています。全体像の把握には役立ちますが、これだけでは要件を導出するには不十分です。
• 浅い — API カタログ、機能概要、またはマーケティングレベルの要約です。何があるかは列挙されていますが、どのように動作するか、どのように失敗するか、どのような契約を強制するかは記載されていません。スコープの決定には不十分です。

スコープ設定ルール： 監査対象を、詳細なドキュメントがあるサブシステムだけに絞ってはいけません。最も複雑なモジュール、または最も障害が発生しやすいモジュールのドキュメントが浅い場合、それはモジュールをスキップする理由ではなく、PROGRESS.md に記録すべきドキュメントのギャップです。リスクが最も高く、ドキュメントが最も薄いコードにこそ、バグが潜んでいます。ドキュメントが整った領域だけを監査すると、安全そうに見える一方で、実際の欠陥を見逃すレポートになります。

高リスク領域のドキュメントが浅い場合：

1. PROGRESS.md の ## Documentation depth assessment セクションに、ギャップを明記します。
2. ソースコード（ドキュメントコメント、安全性アノテーション、防御的パターン、既存のテスト）から直接要件を導出し、[Req: inferred — from source] とタグ付けします。
3. 完全性レポートで、その領域についてさらに詳細なドキュメントの収集が必要であることを記録します。

レビュー担当者が、ドキュメントがスコープに適切に反映されたかを評価できるよう、reference_docs/ 内の各ファイルの深さの分類を PROGRESS.md に記録します。

カバレッジ確約テーブル： reference_docs/ 内のすべてのドキュメントを分類した後、PROGRESS.md の ## Documentation depth assessment セクションに次のテーブルを作成します。

ドキュメント	深さ	サブシステム	要件に関する確約	除外する場合：理由

詳細なドキュメントごとに、対象のサブシステムを対応付けたうえで、そのドキュメントから要件を導出することを確約（「フェーズ 2 で対応」）するか、トレードオフを明示した具体的な理由を記載します。「今回の実行では対象外」のような文だけでは不十分です。たとえば、「今回の実行はパーサー／コンパイラー／GC パイプラインに焦点を当てるため、インタープリターの JIT は除外します。別途実行することを推奨します」のように、理由を説明する必要があります。

ゲート： reference_docs/ に詳細なドキュメントがある高リスクのサブシステムを、要件セットから黙って除外してはいけません。詳細なドキュメントに「対応する」と確約しているにもかかわらず、ステップ 7 の終了時点でそこから導出された要件が 0 件である場合、要件の導出プロセスは未完了です。フェーズ 2 の成果物生成に進む前に戻り、要件の不足分を導出してください。

ステップ 2：アーキテクチャを把握する

ソースディレクトリとその用途を一覧にします。メインのエントリーポイントを読み、実行フローを追跡します。次の項目を特定します。

• 主要なサブシステム 3～5 個
• データフロー（入力 → 処理 → 出力）
• 最も複雑なモジュール
• 最も壊れやすいモジュール

ステップ 3：既存のテストを読む

既存のテストファイルをすべて読みます。小規模・中規模のプロジェクトではすべてのファイルを、大規模なプロジェクトでは各サブシステムの代表的なサンプルを読みます。テスト数、カバレッジの傾向、ギャップ、そして見栄えはよいものの実際のバグを検出できないカバレッジの見せかけを特定します。

重要：インポートパターンを記録してください。 既存のテストがプロジェクトのモジュールをどのようにインポートしているかを確認します。言語ごとに慣例は異なります（Python の sys.path 操作、Java／Scala のパッケージインポート、TypeScript の相対パスまたはエイリアス、Go のパッケージ／モジュールパス、Rust の use crate:: または use myproject::）。機能テストでも、まったく同じパターンを使う必要があります。これを間違えると、すべてのテストがインポート／解決エラーで失敗します。6 言語の一覧については、references/functional_tests.md §「インポートパターン」を参照してください。

統合テストの実行方法を特定します。 実際の外部サービス（API、データベースなど）を使用して、システムをエンドツーエンドでテストするスクリプトまたはテストファイルを探します。そのパターンを記録してください。RUN_INTEGRATION_TESTS.md の作成時に必要になります。

ステップ 4：仕様を読む

各仕様書の各セクションを順に読みます。すべてのセクションについて、「どのようなテスト可能な要件を述べているか」と考えます。対応するテストがない仕様上の要件を記録します。これらのギャップを機能テストで埋めます。

推定要件（テスト、型、またはコードの動作から推定した要件）を使う場合は、ステップ 1 で定義した [Req: tier — source] 形式で、それぞれの確信度を付けてください。推定要件は QUALITY.md のシナリオに反映し、フェーズ 7 でユーザーに確認してもらう必要があります。

ステップ 4b：関数シグネチャと実データを読む

テストを書く前に、各関数の呼び出し方を正確に把握する必要があります。ステップ 2 で特定したすべてのモジュールについて、次の作業を行います。

1. 実際の関数シグネチャを読みます — パラメーター名、型、デフォルト値を確認します。使用状況から推測せず、関数の定義とドキュメント（Python の docstring、Java／Scala の Javadoc／ScalaDoc、TypeScript の型注釈、Go の godoc コメント、Rust の doc コメントと型シグネチャ）を読みます。
2. 実データファイルを読みます — プロジェクトに項目ファイル、フィクスチャファイル、設定ファイル、サンプルデータ（pipelines/、fixtures/、test_data/、examples/ 内）がある場合は、それらを読みます。テストフィクスチャは、実際のデータ形式と正確に一致させる必要があります。
3. 既存のテストフィクスチャを読みます — 既存のテストがテストデータをどのように作成しているかを確認します。そのパターンを踏襲してください。特定のキーを使って設定辞書を作成している場合は、同じキーを使います。
4. ライブラリのバージョンを確認します — プロジェクトの依存関係マニフェスト（requirements.txt、build.sbt、package.json、pom.xml／build.gradle、go.mod、Cargo.toml）を確認し、実際に利用可能なものを把握します。インストールされていないライブラリ機能に依存するテストを書かないでください。依存関係がない可能性がある場合は、テストフレームワークのスキップ機能を使います。フレームワークごとの例については、references/functional_tests.md §「ライブラリのバージョンへの対応」を参照してください。

関数呼び出しマップを記録します。テストする各関数について、関数名、モジュール、パラメーター、戻り値を書き留めます。このマップにより、テスト失敗の最も一般的な原因である、間違った引数での関数呼び出しを防げます。

ステップ 5：過去の問題を探す

これは最も重要なステップです。防御的なコードパターンを検索してください。それぞれが、過去の障害や既知のリスクを示す証拠です。

これが重要な理由： 開発者は、楽しみで try/except ブロックや null チェック、リトライロジックを書くわけではありません。防御的なコードはすべて、誰かが痛い目に遭ったために存在しています。JSON の解析を囲む try/except は、本番環境で不正な JSON が発生したことを意味します。フィールドへの null チェックは、本来あってはならない場面でそのフィールドが欠落していたことを意味します。こうしたパターンは、コードベースが障害の歴史をささやいているのです。それぞれを、目的適合性のシナリオと境界テストに反映します。

体系的な検索方法、grep パターン、見つけた内容を目的適合性のシナリオと境界テストに変換する方法については、references/defensive_patterns.md を読んでください。

最低基準：コアとなる各ソースファイルで、防御的なパターンを少なくとも 2～3 個見つけてください。それより少ない場合は、ざっと目を通しただけです。シグネチャだけでなく、関数本体も読んでください。

ステップ 5a：状態マシンを追跡する

プロジェクトに何らかの状態管理（ステータスフィールド、ライフサイクルのフェーズ、ワークフローの段階、モードフラグ）がある場合は、状態マシンを漏れなく追跡してください。これにより、防御的パターンの分析だけでは見落とす種類のバグ、つまり存在するのに処理されていない状態を見つけられます。

状態マシンの見つけ方： モデル、列挙型、定数の中から、ステータスや状態を表すフィールドを検索します（例：status、state、phase、mode）。アクションを許可する前にステータスを確認するガードを検索します（例：if status == "running"、match self.state）。状態遷移（ステータスフィールドへの代入）を検索します。

見つかった状態マシンごとに、次のことを行います。

1. 考えられる状態をすべて列挙します。 列挙型や定数を確認するか、フィールドに代入される値をすべて grep して、漏れなく列挙します。
2. 状態を使用する各箇所（UI ハンドラー、API エンドポイント、制御フローのガード）について、考えられるすべての状態を処理しているか確認します。意味のあるデフォルト処理がない switch／match や、すべての状態を網羅していない if/elif チェーンは、抜け漏れです。
3. 各状態遷移について、すべての状態に到達できるか確認します。一度入ると抜け出せない状態はありますか？利用可能であるべき操作を妨げる状態はありますか？
4. 抜け漏れを調査結果として記録します。 たとえば、ステータスガードが「running」ではアクション X を許可するのに、「stuck」では許可しない場合、ユーザーが停止中のプロセスにもアクション X を実行する必要があるなら、これは実際のバグです。プロセスが終端状態に入ってもクリーンアップが実行されない場合も、実際のバグです。

これが重要な理由： 状態マシンの抜け漏れは、通常の運用時には見えず、負荷やエッジケースで表面化するバグを引き起こします。まさにシステムが正常に動作する必要があるときに発生します。「stuck」状態で強制終了できないバッチプロセッサー、すべての作業が完了しても自動終了しないウォッチャー、「pending」の実行を再開できない UI は、いずれも不完全な状態処理の兆候です。コードがそれらに対処できていないだけで、防御しているわけではないため、こうしたバグは防御的パターンの分析では見つかりません。

ステップ 5b：スキーマ型を対応付ける

プロジェクトに検証レイヤー（Python の Pydantic モデル、JSON Schema、TypeScript のインターフェース／Zod スキーマ、Java Bean Validation アノテーション、Scala の case class コーデック）がある場合は、ここでスキーマ定義を読みます。防御的パターンが見つかった各フィールドについて、スキーマが受け入れる値と拒否する値を記録します。

対応付けの形式と、有効な境界テストを書くうえでこれが重要な理由については、references/schema_mapping.md を読んでください。

ステップ 6：ドメイン知識に基づくリスク分析（コード＋ドメイン知識）

これは、ライブラリやフレームワークのコードベースでバグを探すための主要な調査です。 構造化パターンを選ぶ前に完了してください。結果はすぐに EXPLORATION.md の ## Quality Risks セクションに記録し、記憶に留めておかないでください。

プロジェクトごとに、障害の傾向は異なります。このステップでは、コードの調査だけでなく、類似システムで何がうまくいかなくなるかという学習済みの知識も含め、2 つの情報源を使います。 コードの調査から、次の点を確認します。

• このプロジェクトで「気づかれないまま誤っている」とは、どのような状態でしょうか？
• どの外部依存関係が、予告なく変わる可能性がありますか？
• 何が単純そうに見えて、実際には複雑でしょうか？
• 横断的な関心事はどこに隠れているでしょうか？

ドメイン知識から、次の点を確認します。

• 「このようなシステムでは、何が問題になりますか？」――HTTP ルーターなら、ヘッダー解析のエッジケース（品質値、トークンリスト、大文字と小文字の区別）、ミドルウェアの順序に関する依存関係、パスの正規化を考えます。HTTP クライアントなら、リダイレクト時の認証情報の削除、エンコーディングの検出、接続状態の漏洩を考えます。シリアライゼーションライブラリなら、null の扱いにおける非対称性、直接メソッドとビューラッパー間の API サーフェスの一貫性、遅延評価のキャッシュの不具合、往復変換の忠実性を考えます。Web フレームワークなら、レスポンスヘルパーのエッジケース、設定のコンパイルチェーン、ミドルウェアの状態分離を考えます。バッチプロセッサなら、クラッシュからの復旧、冪等性、気づかれないデータ損失、状態の破損を考えます。乱数や統計を扱う場合は、シード、相関、分布の偏りを考えます。
• 「正しそうな出力を生成するものの、実際には誤っているのは何でしょうか？」――これは最も危険な種類のバグです。すべてのチェックを通過するものの、微妙に破損している出力です。200 OK なのに Content-Type が誤っているレスポンス。認証情報を漏らしながらも成功するリダイレクト。値が気づかれないまま切り詰められたデシリアライズ済みオブジェクト。
• 「1 倍では起きないものの、10 倍の規模では何が起きますか？」――チャンク境界、レート制限、タイムアウトの連鎖、メモリ負荷です。
• 「最悪のタイミングでこのプロセスが強制終了されたら、何が起きますか？」――書き込みの途中、トランザクションの途中、バッチ送信の途中です。
• 「同じように動作するはずの 2 つのインターフェイスが、エッジケースの入力でどこから食い違いますか？」――オーバーロード、エイリアス、同期／非同期 API、ビルダー API と直接 API、直接変更子とライブビュー／ラッパー、標準ライブラリ互換のラッパーとフレームワーク固有のインターフェイスです。Java/Kotlin の場合：add(null) と asList().add(null)、put(key,null) と asMap().put(key,null)。Python の場合：コンストラクターでのエンコーディングと変更子でのエンコーディング、同期クライアントと非同期クライアントの動作です。
• 「もっともらしい出力を、微妙に誤ったメタデータとともに生成するものは何でしょうか？」――コンテントタイプ、文字セット、ルートパターン、ETag の強度、バイト数、認証情報／ヘッダー／Cookie の伝播、ステータスコード、キャッシュバリデーターです。
• 「標準的な文法やリスト構文を、場当たり的な文字列処理で解析していませんか？」――品質値（q=0）、カンマ区切りのヘッダー、ダイジェスト認証チャレンジ、パラメーター付き MIME タイプ、クエリ文字列、列挙値／キーワードのセット、Cookie のマージです。
• 「ドメインの専門家なら、どのようなエッジケースの入力を思いつくでしょうか？」――HTTP コードなら、Accept-Encoding: gzip;q=0、Connection: keep-alive, Upgrade、Content-Type: application/problem+json。シリアライゼーションコードなら、異なる API サーフェスを通した null、Integer.MAX_VALUE + 1 の値、エンコードしてからデコードする往復変換。ルーティングコードなら、重複するパターン、マウントされたプレフィックスの伝播、メソッドが異なる同じパスです。
• 「取り消し不能または高コストの操作を実行する前に、ユーザーが知っておく必要がある情報は何でしょうか？」――実行前のコスト見積もり、対象範囲の確認（特に、ファンアウトや拡張によって作業量が増える場合）、リソースに関する警告です。何を実行しようとしているかを示さずに、何時間もの処理や多額のコストをユーザーに気づかれないまま負わせられるシステムには、安全策が欠けています。長時間実行プロセスの開始、バッチジョブの送信、拡張／ファンアウトのトリガーとなる操作を探し、取り返しのつかない時点より前に、実際の数値を使ったプレビュー、見積もり、または確認をユーザーに提示しているか確認します。
• 「長時間実行プロセスが終了したとき、実際に停止しますか？」――ポーリングループ、ウォッチャー、バックグラウンドスレッド、完了まで動作するデーモンプロセスには、明示的な終了条件が必要です。ループが「作業はまだありますか？」を確認していても、「すべての作業が完了しましたか？」を確認していなければ、完了後も無限に動き続けます。これは特に、バッチプロセッサやキューコンシューマーでよく見られます。 この知識から、優先順位を付けた失敗シナリオを少なくとも5件生成してください。実際にこれらの失敗を観測している必要はありません。この種のシステムで発生することを、学習を通じて知っているはずです。ファイルパスと行番号の引用を含む、具体的なバグ仮説として優先順位順に記述してください。それぞれを次の形式にします。「[ファイル:行番号] のコードが [X] を行うため、[ドメイン固有のエッジケース] によって、[正しい動作] ではなく [誤った動作] が発生します。」さらに、実際に調査したコードを根拠として示します。「persistence.py の340行目付近（save_state）を読み、一時ファイルとリネームのパターンを確認してください。」

ゲートで不合格になるアンチパターン： すでにコードにある防御的なパターン（コードが適切に処理していること）を列挙する「品質リスク」セクションは、リスク分析ではなく安心材料の羅列であり、バグを見つけられません。具体的な失敗シナリオなしにリスクのあるモジュールを列挙するセクションは、対処につながりません。「成熟していて十分にテストされたライブラリなので、基本的なバグは起きにくい」と結論付けるセクションは、実害をもたらします。成熟したライブラリでは、明白なバグは何年も前に見つかっているからこそ、API 契約やエッジケースに関する最も微妙なバグが潜んでいます。判定基準：コードレビュアーが各シナリオを読んで、どの関数を開き、どの入力をテストすべきかすぐに分かるでしょうか。そうでなければ、そのシナリオは抽象的すぎます。

ステップ 7：テスト可能な要件を導き出す

完全な5フェーズのパイプライン、ドメインチェックリスト、バージョニング手順については、references/requirements_pipeline.md を読んでください。

これは、コードレビュープロトコルで最も重要なステップです。調査で見つかったすべての情報（仕様、ChangeLog の項目、設定用構造体、ソースコメント、チャット履歴）を、コードレビューで検証するテスト可能な要件に集約します。このパイプラインでは、契約の発見と要件の導出を分離し、ファイルベースの外部メモリを使用して、完全性ゲートによる機械的な検証を行います。

重要な理由： 構造的なコードレビューで見つかる実際の欠陥は約65％です。残りの35％は意図への違反、つまり存在しないことによるバグ、ファイル間の矛盾、設計上の不足です。コードリーディングだけでは、そこにあるコード自体が正しいため、こうした問題は見つかりません。コードが本来どう動作すべきかを把握し、そのとおりに動作するかを確認する必要があります。そのために使うのが、テスト可能な要件です。

5フェーズのパイプライン：

1. フェーズ A — 契約の抽出。 すべてのソースファイルを読み、動作上の契約をすべて列挙します。quality/CONTRACTS.md に記録します。これは発見の段階です。明白に思えるものも含め、すべて列挙してください。

2. フェーズ B — 要件の導出。 CONTRACTS.md とドキュメントを読みます。関連する契約をまとめ、ユーザーの意図を補足して、正式な要件を記述します。REQ レコードを quality/requirements_manifest.json（信頼できる唯一の情報源）に記録し、quality/REQUIREMENTS.md に出力します。各要件について、tier（schemas.md §3.1 に基づく1～5）を記録します。また、tier ∈ {1, 2} の場合は、schemas.md §5.4 / §5.5 に従って bin/reference_docs_ingest が bin/citation_verifier を呼び出して生成した citation ブロックを記録します。LLM が citation_verifier を直接シェルから実行することはありません。この抜粋は ingest パイプラインによって生成され、ゲート実行時に quality_gate.py によって再検証されます。Tier 3 の REQ（コードが仕様）では、description にソースの file:line を記載します。引用は FORMAL_DOC の参照に限られ、Tier 3/4/5 の REQ に記載してはいけません。tier と citation の組み合わせが、追跡可能性の連鎖（reference_docs/cite → requirements → bugs → tests）の起点となります。フィールドの全一覧と Tier 1 を Tier 2 より優先するルールについては、このステップの後半にある tier/citation の説明ブロックを参照してください。

   REQ の任意項目 Pattern:。 フェーズ3で補償グリッドが必要な要件では、パターンクラスを宣言します。

   • Pattern: whitelist — 権威ある項目一覧です。すべての箇所で各項目を処理する必要があります。
   • Pattern: parity — 対称的な操作は一致させる必要があります （encode↔decode、setup↔teardown）。
   • Pattern: compensation — 共有された不備を補う必要がある箇所です。 このフィールドが欠けている場合、グリッドは作成されません。無効な値を設定すると quality_gate.py が失敗します。

   保持ルール（Phase 2）。 Pattern: は設計上はオプションです（単一箇所の REQ でグリッドが不要な場合もあります）。しかし、Phase 1 の仮説にすでに含まれていた場合は、保持が必須です。Phase 2 では、Pattern: が存在する場合は必ず EXPLORATION.md から quality/REQUIREMENTS.md および quality/requirements_manifest.json へ転記しなければなりません。黙って省略することは、文書化された v1.4.5 のリグレッションの発生経路です。パターンタグが付いていることを知らない REQ に対しては、Phase 5 のカーディナリティゲートがカバレッジを強制できないためです。ゲートの構造的なバックストップ（C13.7/Fix 2）は、サイトごとの UC 参照（Phase 1 の直積 UC ルールが生成する UC-N.a/UC-N.b 形式）を持つ REQ を相互チェックし、そのような REQ に Pattern が欠けている場合はゲートを失敗させます。

   コード存在の主張に対する一次ソース抽出ルール。 特定の定数、値、ラベルが特定の関数で処理されることを主張する要件（例：「whitelist は X、Y、Z を保持しなければならない」）を書く場合、要件は、仕様が「そこにあるべき」とするものと、コードが実際に含んでいるものを区別しなければなりません。コードから実際の内容（case ラベル、マップのキー、if-else の分岐）を抽出し、仕様の一覧と比較してください。定数が仕様には現れるがコードには存在しない場合、要件は「X を処理しなければならない — [NOT IN CODE]: header.h:NN で定義されているが、file.c:NN-NN の function() には存在しない」と記述してください。X が実際に保持されていることを検証せずに「X を保持しなければならない」と書いてはいけません。これにより、要件がコードの存在を主張し、コードレビューがその主張をコピーし、仕様監査がそれを引き継ぎ、トリアージがそれを受け入れてしまう、という汚染の連鎖を防ぎます。この正確な連鎖は v1.3.17 の virtio テストで観測されました。REQUIREMENTS.md が switch 内で RING_RESET が保持されていると主張し、コードレビューがその一覧をコピーし、3 人の仕様監査者がその主張を引き継いだため、バグが検出されずに残ったのです。

   ディスパッチ関数に対する機械的検証アーティファクト（必須）。 契約が、関数が一連の名前付き定数（feature bit、enum 値、オペコードテーブル、イベント型、ハンドラレジストリ）を処理、保持、またはディスパッチすると主張する場合、契約行を書く前に、関数本体から実際の case ラベル／分岐を機械的に抽出するシェルコマンドまたはスクリプトを生成し、実行しなければなりません。生の出力を quality/mechanical/<function>_cases.txt に保存してください。コマンドは非対話的なパイプライン（例：awk + grep）でなければならず、ファイルのバイト列を読み取って一致箇所を出力するため、幻覚は起こり得ません。例：

   awk '/void vring_transport_features/,/^}$/' drivers/virtio/virtio_ring.c \
     | grep -E '^\s*case\s+' > quality/mechanical/vring_transport_features_cases.txt
   

   実行後、出力ファイルを読み込み、関数が何を処理するかの唯一の正とします。「関数は定数 X を保持する」という契約行は、quality/mechanical/<function>_cases.txt に対応する case X: 行が含まれていない限り禁止です。定数が仕様やヘッダには現れるが機械的出力には現れない場合、契約はそれを不在として記録しなければなりません："must handle X — **[NOT IN CODE]**: header.h:NN で定義されているが、機械的チェックによれば function() には存在しない。" 後続の成果物（REQUIREMENTS.md、RUN_SPEC_AUDIT.md、コードレビュー）は、ディスパッチ関数のカバレッジに言及する際に機械的ファイルのパスを引用しなければなりません。手書きの一覧で機械的出力を置き換えてはなりません。

   機械的アーティファクトの整合性チェック（必須）。 機械的抽出の各コマンドは、検証ステップとして quality/mechanical/verify.sh にも追記してください。スクリプトは同じ抽出パイプラインを再実行し、結果を保存済みファイルと diff しなければなりません。verify.sh は次の構造で生成してください：

   #!/bin/bash
   # Auto-generated: re-run mechanical extraction commands and verify saved artifacts
   set -euo pipefail
   FAIL=0
   
   # Verify <function>
   ACTUAL=$(awk '/void vring_transport_features/,/^}$/' drivers/virtio/virtio_ring.c | grep -nE '^\s*case\s+')
   SAVED=$(cat quality/mechanical/vring_transport_features_cases.txt)
   if [ "$ACTUAL" != "$SAVED" ]; then
     echo "MISMATCH: vring_transport_features_cases.txt"
     diff <(echo "$ACTUAL") <(echo "$SAVED") || true
     FAIL=1
   else
     echo "OK: vring_transport_features_cases.txt"
   fi
   
   exit $FAIL
   

   フェーズ6では bash quality/mechanical/verify.sh を必ず実行してください。成果物に不一致があった場合、ベンチマークは失敗します。これは v1.3.19 で観測された障害パターンを検出するためのものです。モデルは抽出コマンドを実行したものの、シェルのリダイレクトによる出力取得を使わず、自分で想定した出力をファイルに書き込んでいました。その結果、実際のコマンドでは生成されない case VIRTIO_F_RING_RESET: 行が挿入されていました。同じコマンドを別のステップで再実行し、ファイルと差分を取ることで、この改ざんを検出できます。

   即時の整合性ゲート（必須、フェーズ2a）。 *_cases.txt ファイルを書き出した直後に、かつ抽出結果を引用するコントラクト、要件、または説明文の成果物を書く前に、bash quality/mechanical/verify.sh を即座に実行してください。終了コードが 0 でない場合は、処理を停止し、失敗した *_cases.txt を削除して、新しいシェルリダイレクトで抽出コマンドを再実行してください（出力を手で編集しないでください）。その後、再検証してください。verify.sh が終了コード 0 で終わるまで、フェーズ3/2c に進まないでください。verify.sh の標準出力と終了コードは、永続的な証跡ファイルとして quality/results/mechanical-verify.log と quality/results/mechanical-verify.exit に保存してください。このゲートが必要なのは、v1.3.23 で検証をフェーズ6まで先送りすると、後続の成果物（CONTRACTS.md、REQUIREMENTS.md、トリアージプローブ）が偽造された抽出結果の上に構築されてしまうことが分かったためです。モデルは要件と成果物の不一致を、要件を修正するのではなく成果物を壊すことで解消していました。

   抽出後のメカニカル成果物は不変です。 シェルリダイレクトで *_cases.txt ファイルが書き出され、verify.sh で検証されたら、その実行の残りの間は、変更、上書き、再生成をしてはいけません。後続のステップでメカニカル成果物と要件またはコントラクトの間に不一致が見つかった場合、誤っているのは成果物ではなく要件またはコントラクトです。抽出結果ではなく説明文を修正してください。このルールは、v1.3.23 で、モデルが自身の筋書きに合わせるために、正しい抽出結果を捏造内容で上書きしてしまった障害パターンを防ぐためのものです。

   禁止されたプローブのパターン（トリアージと検証）。 トリアージプローブ、検証プローブ、監査のアサーションでは、特定の行にソースファイルが何を含むかの唯一の根拠として、open('quality/mechanical/...') や cat quality/mechanical/... を使用してはいけません。関数 F が行 N で定数 C を扱っていることを確認するには、プローブは次のいずれかを行う必要があります。(a) ソースファイルを直接読み込み（open('drivers/virtio/virtio_ring.c') を使い、行を固定したアサーションを行う）、または (b) verify.sh が使う同じ抽出パイプラインを再実行し、その出力を確認する。保存された成果物を読むだけでは、成果物が何を述べているかしか証明できず、コードが何を述べているかは証明できません。これは循環的な検証です。v1.3.23 では、プローブ C がソースコードではなく偽造された成果物を検証してしまい、捏造されたデータで合格していました。

   空の mechanical/ ディレクトリを作成しないでください。 プロジェクトのコントラクトに、メカニカル抽出を必要とするディスパッチ関数、レジストリ、または列挙チェックが含まれている場合にのみ quality/mechanical/ を作成してください。そのようなコントラクトがなければ、ディレクトリ自体を作成せず、PROGRESS.md に次のように記録してください: Mechanical verification: NOT APPLICABLE — no dispatch/registry/enumeration contracts in scope. 空の mechanical/ ディレクトリ（または verify.sh のないディレクトリ）を作成することは規格に適合しません。これは、抽出が試みられた後に放棄されたことを示してしまいます。ディレクトリを作成する前に判断してください。このプロジェクトにディスパッチ関数のコントラクトはありますか。ない場合は mkdir を実行しないでください。ある場合は、完全に作り込んでください。 規範的記述と記述的記述の区別。 要件と契約には、期待される動作について規範的な表現（「保持しなければならない」「処理するべきである」）を使用する必要があります。機械的な検証成果物によって主張が確認された場合に限り、記述的な表現（「保持する」「処理する」）を使用できます。確認を裏付ける機械的な成果物がない状態で「実装は VIRTIO_F_RING_RESET を保持する」と記載した要件は、適合していません。「実装は VIRTIO_F_RING_RESET を保持しなければならない」と記載し、その定数が現在存在するかどうかを示す機械的なチェック結果を引用してください。

3. フェーズ C — カバレッジ検証。 すべての契約をすべての要件と照合します。抜けを修正します。カバレッジが 100% に達するまで、最大 3 回繰り返します。quality/COVERAGE_MATRIX.md に記載します。このマトリックスは、要件ごと（REQ-001、REQ-002 など）に1 行を割り当てなければなりません。「C-001 to C-007 | REQ-001, REQ-003」のような範囲をまとめた行は使用しないでください。範囲をまとめると機械的な検証が不可能になり、抜けが隠れてしまいます。

4. フェーズ D — 完全性チェックと自己改善ループ。 ドメインチェックリスト、テスト可能性の監査、要件間の整合性チェックを適用します。また、カバレッジコミットメント表で「will cover」と約束されているすべての詳細ドキュメントに、少なくとも 1 つの要件が紐付いていることを確認します。紐付いていない場合は、続行する前に抜けを補う要件を追加します。

   quality/COMPLETENESS_REPORT.md には、ベースラインの完全性レポートとして記載します（## Verdict セクションは含めないでください。判定はフェーズ 5 の調整後に行い、クローズに有効な唯一の判定を生成します）。その後、最大 3 回の自己改善を繰り返します。レポートを読み、抜けを修正し、再チェックします。各回の変更が 3 件未満になったら早期終了します。

5. フェーズ E — ナラティブの整理。 プロジェクト概要を追加し（概要検証ゲートを実施）、続いてユースケースを導出します（ユースケース導出ゲートを実施）。カテゴリ別のナラティブ、横断的な懸念事項、最終的な並べ替えに進む前に、両方のゲートに合格する必要があります。この順序により、後半のゲートに失敗した場合に導出をやり直す複数回のループを防ぎます。上位から下位へ流れるように並べ替えます。番号を連番にします。

REQUIREMENTS.md は、人が読める概要から始めなければなりません。 概要では、次の問いに答えてください。このプロジェクトは何か。何をするのか。関係者（ユーザー、システム、ハードウェア、プロトコル）は誰か。最もリスクの高い領域はどこか。この概要は、プロジェクトを初めて知る人にとって役立つものでなければなりません。すべての関係者がシステムであるライブラリやドライバーの場合は、システム上の関係者（カーネルメンテナー、プロトコルの対向実装、インテグレーター、エンドユーザー開発者）と、その相互作用について説明してください。生のスコープメタデータや HTML コメントから始めず、平易な言葉で説明してください。

概要検証ゲート（必須）。 概要を書いた後、ユースケースの導出に進む前に、次のセルフチェックを行ってください。

この概要は、実際のユーザーが認識するプロジェクトの姿を説明していますか。特に、次の点を確認してください。

• プロジェクトがエコシステムで果たす役割と、実社会での重要性を示していますか。
• 何が、誰に、何のために依存されているかを特定していますか。
• 日常的にこのプロジェクトを使う開発者が、「そう、それがこのプロジェクトであり、重要である理由だ」と言うでしょうか。
• よく知られたプロジェクトの場合、一般に知られている採用状況を反映していますか（例：Cobra → kubectl/Hugo/GitHub CLI、Express → 数百万の Node.js API サーバー、Zod → フォーム検証/tRPC、Serde → Rust のデフォルトのシリアライゼーション層）。

概要が、ソースコードしか読んだことがなく、ソフトウェアを使ったことのない人によって書かれたように見える場合は、先に進む前に修正してください。概要は以降のすべての内容の枠組みとなります。機能中心のユースケースや内部向けの要件は、プロジェクトそのものではなくコードしか説明していない概要の兆候です。

ユースケースの導出（必須、概要ゲートの後に実施）。 検証済みの概要と収集したドキュメントから 5～7 件のユースケースを導出し、コードに照らして検証します。各ユースケースは、次の条件を満たさなければなりません。

• 実際のユーザーの成果を記述し、コード機能は記述しないでください。「開発者が、ネストされたサブコマンド、永続フラグ、シェル補完を備えたCLIツールを構築する」と書き、「フレームワークがコマンドツリーをサポートする」とは書かないでください。
• 具体的なアクターと、そのアクターが達成しようとしていることを明示してください。アクターには、エンドユーザーの開発者、システム管理者、カーネルメンテナー、プロトコルの相手側、インテグレーター、自動化されたコンシューマーが含まれます。
• ソフトウェアの実際のユーザーにとって分かりやすいものにしてください。有名なプロジェクトについては、モデル自身が持つそのプロジェクトに関する知識、コミュニティのドキュメント、チュートリアル、実際の採用パターンに照らして、ユースケースを検証してください。
• 検証可能な満足条件を通じて、少なくとも1つの要件に結び付けてください。

パイプラインは次の問いを明示的に投げかけるべきです。「このプロジェクトの概要、収集されたドキュメント、既知のユーザーベースに基づくと、実際のユーザーがこのソフトウェアで行う最も重要なことは何か。5〜7個挙げよ。」ユースケースは、この問いから導出してください。コードを走査して機能をカテゴリにまとめることから導出してはいけません。

コードに対するユースケースの検証: 概要とドキュメントからユースケースを導出した後、それぞれをコードベースに照らして検証してください。ユースケースが、コードが実際にはサポートしていないことを記述している場合は、修正するか削除してください。重要なユーザーの成果をコードがサポートしているのに、どのユースケースalso対象にしていない場合は、ユースケースを追加してください。目標は、ユーザーにとって分かりやすく、かつコードに裏付けられたユースケースにすることです。

受け入れ基準のスパン確認（必須。ユースケース導出の後に実行）。 ユースケースが確定し、コードに対して検証された後、すべての要件の満足条件を合わせて、プロジェクトの主要な振る舞いを網羅しているかを確認してください。

これらの受け入れ基準を合わせると、プロジェクトを網羅しているか。概要やユースケースに記述された主要なユーザー向けの振る舞いのうち、壊れた場合にどの要件の満足条件でも検出されないものはあるか。

各ユースケースについて、少なくとも1つの要件の満足条件がそのユースケースまで追跡可能でなければならず、かつ紐づいた要件の少なくとも1つは specific（architectural-guidance ではない）でなければなりません。具体的な要件が紐づいていないユースケースは、ギャップを示します。ギャップが見つかった場合は、次のいずれかを行ってください。(a) ギャップを埋めるために新しい要件を追加するか、既存の条件を明確化する。(b) 要件が実際に保護している内容を反映していない場合は、ユースケースを修正する。この確認の結果は、完全性レポートに記録してください。

ユースケースの後に、個々の要件を記述してください。

v1.5.3 のティアと引用方式（schemas.md §3.1、§5）。 すべての REQ は、schemas.md §3.1 に従い、1〜5 の整数の tier を持ちます。

• Tier 1 — プロジェクト自身の正式な仕様（tier=1 の FORMAL_DOC レコード。最も高い権威を持つ）。
• Tier 2 — 外部の正式な標準（RFC、W3C、ISO、公開された API 契約など。tier=2 の FORMAL_DOC レコード）。
• Tier 3 — 正式な仕様が存在しない場合のソースオブトゥルースのコード。コードそのものが仕様となる。
• Tier 4 — トップレベルの reference_docs/ から bin/reference_docs_ingest.load_tier4_context によって読み込まれる非公式ドキュメント（AI チャット、設計メモ、振り返りなど）。
• Tier 5 — ドキュメントの裏付けがなく、コードの振る舞いから推論されたもの。

tier ∈ {1, 2} の場合、REQ には schemas.md §5 に従った citation ブロックも含めなければなりません。このブロックには、document、document_sha256、section/line のうち少なくとも1つ、および機械的に抽出された citation_excerpt を含めます。citation_excerpt は手で書いてはいけません。この抜粋は、取り込み時に bin/reference_docs_ingest が、schemas.md §5.4 の決定的アルゴリズム（§5.5 のセクション解決を含む）に従って bin/citation_verifier を呼び出すことで生成されます。LLM は formal_docs_manifest.json から抜粋を取得するだけで、検証器を直接呼び出すことはありません。取り込み時の抽出こそが、幻覚ゲートの第1層を機能させる仕組みです。quality/formal_docs_manifest.json にあるドキュメント（ハッシュとロケーターを含む）を引用できない場合、その REQ は最大でも Tier 3 です。page のみのロケーターは診断専用であり、決して十分ではありません。 Tier 1 が Tier 2 に優先するルール。 プロジェクト独自の仕様（Tier 1）と外部標準（Tier 2）が矛盾する場合は、プロジェクトの立場を引用して、Tier 1 の REQ として記録します。プロジェクトが外部標準から逸脱していることを文書で明示している場合、それは正式な意図であり、不具合ではありません。upstream-spec-issue の判定が適用されるのは、プロジェクトの仕様にその矛盾についての記述がない場合に限られます。

仕様ギャップへの縮退（有効な出力状態）。 formal_docs_manifest.json に、プロジェクト独自の動作を対象とする FORMAL_DOC レコードが一つも含まれていない場合、すべての REQ は Tier 3/4/5 となり、実行は仕様ギャップアナライザーへと適切に縮退します。完全性レポートでは、メタ所見「Tier 1/2 の要件が 0 件」を失敗ではなく指標として報告してください。Tier の分布を実際より豊かに見せるために、引用を捏造してはなりません。quality_gate.py は、検証時に §5.4 に従って bin/citation_verifier を再実行し（extract_excerpt 経由）、citation_excerpt が新たに抽出された内容とバイト単位で一致しない Tier 1/2 の REQ を拒否します（schemas.md §10 invariant #11）。

functional_section は必須フィールドです。 すべての REQ に、関連する REQ をまとめる短い functional_section 文字列（例："Authentication"、"Bus enumeration"）を指定します。これはコードとドキュメントに基づいて LLM が導出するものであり、事前定義されたオントロジーはありません。Phase 2 のレンダリングでは、REQ がこれらのセクションごとにグループ化されます（各セクションには短い導入段落が付きます）。Phase 4 では、Council がグループ分けの一貫性を確認します。schemas.md §6.1 を参照してください。

トレーサビリティは一方向です：REQ → UC。 REQ は UC-NN ID の use_cases[] リストを持ちます。UC レコードには requirements[] の逆リンクを持たせません。逆方向の関係は、レンダリング時に REQ レコードを照会して、一致するエントリーを検索することで導出します（schemas.md §7）。UC レコードに requirements[] フィールドを設定しないでください。

各要件には、以下のフィールドをすべて指定してください：

• ID：REQ-NNN（ゼロ埋めした3桁の連番）。

• タイトル：短い1行の記述。

• ティア：schemas.md §3.1 に従った整数1～5。

• 機能セクション：LLM から導出した短い文字列（上記を参照）。

• 引用（tier ∈ {1, 2} の場合は必須）：bin/reference_docs_ingest が bin/citation_verifier を呼び出して生成します。手動で作成してはならず、LLM から直接呼び出してはなりません。形式は schemas.md §5.1 に従います。

• 要約／説明：要件をテスト可能なアサーションとして記述します。「X は Y を満たす必要がある」または「A の場合、システムは B を実行する必要がある」のようにします。

• ユーザーストーリー：呼び出し元の視点から記述します。「[アクション]を行う[ロール]として、[結果]を得るために、[動作]を期待します。」。「結果を得るために」の節は必須です。これは、要件の背後にある意図を明確にするためです。

• 実装メモ：コードがこの要件をどのように実現するか、つまりメカニズム、関連するコードパス、設計上の選択を記述します。

• 満足条件：この要件が満たされていることを証明する、具体的でテスト可能なシナリオを記述します。正常系、エッジケース、失敗モードを含めてください。この要件にまとめられた Phase A の個々の契約は、それぞれ満足条件となります。

• 代替パス：すべて要件を満たす必要がある、複数のコードパス、モード、エントリーポイントです。代替パスにはバグが潜みやすいものです。

• ユースケース：use_cases[] — この REQ が関与する UC-NN ID のリスト。一方向の前方リンクです。

• 参照：出典を記載します。仕様のセクション、ChangeLog のエントリ、設定フィールドの定義、ソースコードのコメント、課題番号、ドメイン知識などです。Tier 1/2 の REQ では、citation ブロックに正式な参照先が含まれます。自由形式の参照は補足情報です。

• 具体性：具体的（テスト可能。コードレビュー担当者が特定のコード箇所または動作と照合できる満足条件を持つ必要があります。これがデフォルトであり、カバレッジ指標に算入されます）またはアーキテクチャ上の指針（個々のコードパスに照らしてテストできないもの。「軽量で標準ライブラリとの互換性を維持する」や「no_std のサポート」など、横断的な特性を扱います。品質憲章には反映されますが、カバレッジ指標には算入されません。ほとんどのプロジェクトでは、アーキテクチャ上の指針は0～3件にする必要があります。3件を超える場合は、以下の必須セルフチェックが必要です）。「方向性」というカテゴリは廃止されました。以前「方向性」に分類されていた要件は、テスト可能な条件を加えて具体的にするか、明示的にアーキテクチャ上の指針に分類する必要があります。

  アーキテクチャ上の指針のセルフチェック（必須。要件の導出後に実施）。 architectural-guidance のタグが付いた要件の数を数えます。以下の両方の上限・下限を適用してください。

  • 上限（3件超）： 件数が3件を超えた場合は、作業を中断して各要件を再検討します。それぞれについて、「特定のコード箇所に照らしてコードレビュー担当者が検証できる、テスト可能な満足条件を追加できるか」と問いかけます。可能であれば、分類を specific に変更し、その条件を追加します。特定のコードパスに照らして本当に検証できない要件のみを、architectural-guidance のままにします。最終的な件数が3件を超える場合は、超過する各要件について、具体化できない理由を明示的に説明する必要があります。
  • 下限（要件が15件以上の場合は0件）： 要件の合計が15件以上で、architectural-guidance の件数が0件の場合は、横断的な設計上の不変条件がないか要件を再検討します。プロトコルレイヤーをまたぐライブラリ、リソースのライフサイクルを管理するライブラリ、順序の保証を強制するライブラリ、互換性契約を維持するライブラリ（例：「標準ライブラリとの互換性を維持する」「no_std のサポートを維持する」「ワイヤ形式の後方互換性を維持する」）には、通常1～3件のアーキテクチャ上の指針があります。完全性レポートに、該当する要件がなかった理由を1文で記載するか、適切な要件の分類を変更してください。

  件数と分類変更があればその内容を、完全性レポートに記録してください。 要件数に上限を設けないでください。 プロジェクトに必要な数だけ導出してください。小規模なユーティリティなら 20 件程度、成熟したライブラリなら 100 件以上になることもあります。目標は網羅性です。

Step 7a: ドキュメントと要件の突き合わせ

PROGRESS.md のカバレッジ宣言表を読み直してください。「Phase 2 で扱う予定」と宣言した詳細ドキュメントごとに、そのドキュメントが対象とするサブシステムへトレースできる要件が少なくとも 1 件あることを確認してください。要件が宣言済みのサブシステムの一部しかカバーしていない場合は、Step 7 を完了する前にギャップ分の要件を追加してください。

サブシステムごとに、PROGRESS.md に次のいずれかを記録してください。

• そのサブシステムをカバーする要件 ID、または
• 根拠、リスクの承知、推奨される後続対応を付記した明示的な除外

「扱う予定」と宣言しているのに対応する要件がゼロの詳細ドキュメントは、正当なスコープ判断ではなく、プロセスの失敗です。すべての宣言が満たされるか、正当化された除外へ明示的に変換されるまで、成果物の生成に進まないでください。

Step 7b: コードパスから REQ への逆方向トレーサビリティ監査（必須）

実施タイミング: Step 7a と 7b は Phase E の完了後に実施してください（すなわち、オーバービュー検証ゲート、ユースケースの導出、受け入れ基準のスパン確認がすべて完了した後）。この監査は、確定した要件と確定したユースケースの両方に依存します。

要件の導出が完了したら、逆方向トレーサビリティ監査を実行してください。順方向のトレーサビリティ（収集したドキュメント → 要件 → バグ → テスト）は、パイプラインにすでに組み込まれています。このステップでは逆方向を、コードパス単位の粒度で確認します。重要なコードパスは要件の条件へ対応づけられるでしょうか。これは監査活動であり、構造的な双方向リンクではありません。（v1.5.3 における構造的トレーサビリティは schemas.md §7 に従い REQ → UC の一方向であり、スキーマによって強制されています。この監査はコードカバレッジを REQ に照らして確認するもので、別の関心事です。）

この監査は、ファイル単位ではなく パス／分岐／ヘルパー単位 で行います。v1.3.13 ではファイルレベルのカバレッジが 100% でしたが、それでも実在するバグを 2 件見逃していました。問うべきは「このファイルはどこかの要件に対応しているか」ではなく、「この重要な分岐は、ここで何を維持しなければならないかを述べた要件条項に対応しているか」です。

4 つのカテゴリに範囲を限定します（制約のない分岐監査ではありません）。

1. 要件ですでに名指しされている代替パス。 要件がフォールバックや代替パス（例: 「プライマリモードと縮退モード」「ネゴシエーション済みの設定とデフォルト設定」「同期と非同期」）に言及している場合、各代替パスには明示的な 対称性条件 が必要です。対称性条件とは、両方のパスで成り立つべき不変条件を述べたものです。「システムは X と Y の両方を扱う」とだけ書かれ、それぞれについて「扱う」が何を意味するかを specify していない要件は、不完全です。

2. 公開定数を実行時の振る舞いへ変換するヘルパー。 ヘルパー関数が定義済みの定数と実行時の振る舞いの間で、ホワイトリスト化、フィルタリング、変換を行う場合（例: 機能フラグのゲート、コーデックレジストリの参照、機能ホワイトリストのヘルパー）、そのヘルパー専用の要件を設け、維持・変換されるべき値を列挙しなければなりません。

3. 機能ネゴシエーションとフォールバックのロジック。 外部のピアとの間で機能をネゴシエートするコードパス（プロトコルバージョンのネゴシエーション、機能検出、優雅な機能縮退など）には、ネゴシエーションが上位へ進むパスと下位へ戻るパスの両方を対象とする要件が必要です。

4. 以前の BUGS.md、VERSION_HISTORY.md、または仕様監査の出力で名指しされた関数。 過去の実行で特定の関数にバグが見つかっている場合、以降の実行ではその関数について明示的な再確認の証跡（「既知のバグクラスのセンチネル」）を示さなければなりません。これにより「要件の喪失」というリグレッションのクラスを防ぎます。quality/spec_audits/ に過去の仕様監査の出力がある場合は、センチネルチェックを実行する前にそれを読んでください。複数モデルによるカウンシルレビューからの指摘は、既知のバグ箇所を知るうえで価値の高い情報源です。 各カテゴリについて、特定されたパスを対象とする具体的な条件が要件に含まれているか確認します。要件によるカバーがない重要なコードパスである孤立パスは、完全性レポートに「カバレッジギャップ」マーカーを表示する原因になります。完全性レポートで要件が十分であると宣言する前に、要件条件を追加するか、明示的な根拠を示して、これらのギャップを解消する必要があります。

引き継ぎルール： 品質ディレクトリに前回実行時の REQUIREMENTS.md がある場合、パイプラインはそれを読み込み、以前のバージョンの条件が削除されていないか確認する必要があります。条件が削除されていた場合、パイプラインは、次のいずれかを行う必要があります：（a）更新した根拠とともに条件を再導出する、または（b）その条件がもはや関連しない理由を記録する。黙って削除することは認められません。これは、以前に把握した要件が実行間で失われるリグレッションの直接的な原因になります。

パイプライン実行後： Phase 7 では、quality/REVIEW_REQUIREMENTS.md（対話型レビューのプロトコル）と quality/REFINE_REQUIREMENTS.md（要件の改善パスのプロトコル）を生成できます。これらは Phase 2 の成果物ではなく、Phase 7 の対話型改善パスを支援するものです。ユーザーは要件を対話形式でレビューし、異なるモデルで改善パスを実行して、各イテレーションのバージョン付きバックアップを保持できます。バージョン管理プロトコルとバックアップ構造の詳細は、references/requirements_pipeline.md を参照してください。

すべての要件を構造化形式で記録します。これらの要件は、コードレビュープロトコルの検証パスと整合性パスに直接渡されます。

チェックポイント：Phase 1 後に PROGRESS.md を更新する

v1.5.6 の更新 — PROGRESS.md は Phase 1 後ではなく、実行開始時に初期化されるようになりました。 このファイルの前半にある「実行状態の計測」セクションに従い、quality/PROGRESS.md と quality/run_state.jsonl は、フェーズ作業が始まる前に書き込まれます。この時点で Phase 1 の両ファイルはすでに存在します。このチェックポイントは PROGRESS.md の初期化ではなく、Phase 1 の完了時の更新です。

PROGRESS.md の形式は、実行状態ヘッダー（Started／Benchmark／Lever／Runner／Playbook version）、フェーズチェックリスト（現在は quality/run_state.jsonl の phase_start／phase_end イベントに基づいて管理）、および以下の従来のコンテンツセクション（実行メタデータ、成果物一覧、累積 BUG トラッカーなど）を組み合わせたものです。これらは互いに補完するものであり、競合するものではありません。

Phase 1 の完了時に行うこと： 検出事項の数や調査したパターンなどの要約統計とともに、フェーズチェックリストで Phase 1 を [x] にします。Phase 1 の成果物（EXPLORATION.md とすべてのサブ成果物）を成果物一覧に追加します。実行状態の計測セクションにある相互検証ルールに従い、run_state.jsonl に phase_end phase=1 イベントを追記します。

PROGRESS.md が存在する理由： 単一セッションで実行する場合、エージェントはコンテキストをメモリに保持します。しかし、長時間のセッションではコンテキストが劣化し、Phase 1 の検出事項を Phase 6 までに忘れたり、BUG の件数がずれたり、クロージャチェックで確認されなかったために仕様監査の BUG が孤立したりすることがあります。PROGRESS.md は、各フェーズでその状態をディスクに書き込むことで、この問題を解決します。エージェントは各フェーズの前にその内容を読み戻すため、これまでの作業状況を常に正確に把握できます。副次的な効果として、実行が複数のセッションに分割された場合でも、このスキルが正しく機能します。

長時間の実行におけるチェックポイントの運用： 要件パイプラインの各フェーズ（Contracts、Requirements、Coverage Matrix、Completeness、Narrative）の後に、quality/PROGRESS.md を更新し、完了したフェーズ、成果物のパス、現在対象としているサブシステム、残作業、正確な再開地点を記録します。これにより、再開したセッションは作業をやり直すことなく、最後に完了したチェックポイントから続行できます。v1.5.6 に従い、対応する pass_started／pass_ended イベントも run_state.jsonl に追記します。

タイムスタンプの運用： 各フェーズの完了記録は、そのフェーズが終わった直後、次のフェーズを始める前に PROGRESS.md に書き込みます。後からまとめて記録したり、タイムスタンプを遡って補完したりしないでください。タイムスタンプは監査証跡です。Phase 2 の完了時刻が Phase 1 よりも早い場合、レビュー担当者はフェーズが正しい順序で実行されたことを検証できません。チェックポイントの記録を忘れたことに気づいた場合は、その時点で正直なタイムスタンプと間隔が生じた理由を説明する注記を添えて記録します。

v1.5.6 で初期化されたファイルに、Phase 1 の完了時までに入力される PROGRESS.md の完全な形式には、以下のセクションが含まれます（従来のテンプレートは、Phase 5 以降が累積 BUG トラッカーと最終ゲート検証セクションに依存するため、引き続き保持されます）。

# Quality Playbook Progress

## Run metadata
Started: [date/time]
Project: [project name]
Skill version: [read from SKILL.md metadata using the reference file resolution order — must match exactly]
With docs: [yes/no]

## Phase completion
- [x] Phase 1: Exploration — completed [date/time]
- [ ] Phase 2: Artifact generation (QUALITY.md, REQUIREMENTS.md, tests, protocols, RUN_TDD_TESTS.md) — `AGENTS.md` is generated by the orchestrator after Phase 6, not here
- [ ] Phase 3: Code review + regression tests
- [ ] Phase 4: Spec audit + triage
- [ ] Phase 5: Post-review reconciliation + closure verification
- [ ] TDD logs: red-phase log for every confirmed bug, green-phase log for every bug with fix patch
- [ ] Phase 6: Verification benchmarks
- [ ] Phase 7: Present, Explore, Improve (interactive)

## Artifact inventory
| Artifact | Status | Path | Notes |
|----------|--------|------|-------|
| QUALITY.md | pending | | |
| REQUIREMENTS.md | pending | | |
| CONTRACTS.md | pending | | |
| COVERAGE_MATRIX.md | pending | | |
| COMPLETENESS_REPORT.md | pending | | |
| Functional tests | pending | | |
| RUN_CODE_REVIEW.md | pending | | |
| RUN_INTEGRATION_TESTS.md | pending | | |
| BUGS.md | pending | | |
| RUN_TDD_TESTS.md | pending | | |
| RUN_SPEC_AUDIT.md | pending | | |
| tdd-results.json | pending | quality/results/ | Structured TDD output |
| integration-results.json | pending | quality/results/ | Structured integration output |
| Bug writeups | pending | quality/writeups/ | One per TDD-verified bug |

## Cumulative BUG tracker


| # | Source | File:Line | Description | Severity | Closure Status | Test/Exemption |
|---|--------|-----------|-------------|----------|----------------|----------------|



## Terminal Gate Verification


## Exploration summary
[Brief notes on architecture, key modules, spec sources, defensive patterns found]

各フェーズの後にこのファイルを更新します。累積 BUG トラッカーは最も重要なセクションです。どのフェーズで見つかったものであっても、検出事項が孤立しないようにします。

調査結果をディスクに書き込む

PROGRESS.md を初期化した後、調査で得たすべての結果を quality/EXPLORATION.md に書き込みます。このファイルには、コンテキストの境界（セッションの中断、複数パス間の引き継ぎ、長時間実行によるメモリの劣化）を越えて引き継げるよう、Phase 1 で学んだことをすべて記録します。次のような構成にします。

# Exploration Findings

## Domain and Stack
[Language, framework, build system, deployment target]

## Architecture
[Key modules with file paths, entry points, data flow, layering]

## Existing Tests
[Test framework, test count, coverage areas, gaps]

## Specifications
[What reference_docs/ contains, key spec sections, behavioral rules]

## Open Exploration Findings
[At least 8 concrete findings from domain-driven investigation.
Each must have a file path, line number, and specific bug hypothesis.
At least 4 must reference different modules or subsystems.
At least 3 must trace a behavior across 2+ functions.]

## Quality Risks
[At least 5 domain-driven failure scenarios ranked by priority.
Each must name a specific function, file, and line and explain the failure
mechanism using domain knowledge of what goes wrong in systems like this.
These are hypotheses, not confirmed bugs — they tell Phase 2 where to look.
Frame each as: "Because [code at file:line] does [X], a [domain-specific
edge case] will produce [wrong behavior] instead of [correct behavior]."
A section that lists defensive patterns the code already has does NOT belong here.]

## Skeletons and Dispatch
[State machines, dispatch tables, feature registries — with file:line citations]

## Pattern Applicability Matrix
| Pattern | Decision (`FULL` / `SKIP`) | Target modules | Why |
|---|---|---|---|
| Fallback and Degradation Path Parity | | | |
| Dispatcher Return-Value Correctness | | | |
| Cross-Implementation Consistency | | | |
| Enumeration and Representation Completeness | | | |
| API Surface Consistency | | | |
| Spec-Structured Parsing Fidelity | | | |

[3 to 4 patterns must be marked FULL. The rest are SKIP with codebase-specific rationale. Select 4 when a fourth pattern clearly applies and covers different code areas.]

## Pattern Deep Dive — [Pattern Name]
[Use the output format from `exploration_patterns.md`.
Trace the relevant code path across 2+ functions, implementations, or API surfaces.
Each deep dive should pressure-test, refine, or extend findings from the open
exploration and quality risks stages.]

## Pattern Deep Dive — [Pattern Name]
[Repeat for each selected FULL pattern. 3 to 4 deep-dive sections total.]

## Pattern Deep Dive — [Pattern Name]
[Third and final deep dive.]

## Candidate Bugs for Phase 2
[Consolidated from ALL earlier sections — open exploration, quality risks, AND patterns.
Minimum 4 candidates with file:line references. At least 2 from open exploration or
quality risks, at least 1 from a pattern deep dive. For each candidate include the
source stage and what the Phase 2 code review should inspect.]

## Derived Requirements
[REQ-001 through REQ-NNN, each with spec basis and tier]

## Derived Use Cases
[UC-01 through UC-NN, each with actor, trigger, expected outcome]

## Notes for Artifact Generation
[Anything the next phase needs to know — naming conventions, test patterns, framework quirks]

## Gate Self-Check
[Written by the Phase 1 gate. Each check 1–12 with PASS/FAIL and one-line evidence.
This section proves the gate was executed. Do not write this section until you have
actually verified each check against the file contents.]

最低限必要な詳細度： EXPLORATION.md には、実質的な内容が少なくとも 120 行必要です。水増しや定型的な見出しではなく、実際の調査結果（ファイルパス、動作規則、導出した要件、アーキテクチャに関する観察）を記載します。セクション見出しと一行のプレースホルダーだけを並べた骨組みは、有効な引き継ぎ成果物ではありません。内容がこの基準に満たない場合は、Phase 2 に必要な詳細を追加してください。 書き込み後の再読（必須）。 EXPLORATION.md を書き込んだ後、Phase 2 に進む前に、そのファイルをディスクから明示的に読み直してください。これには二つの目的があります：(1) ファイルが正しく書き込まれたことを確認する、(2) 構造化された調査結果をワーキングメモリに読み込み、成果物の生成に備える。この手順を省略して、書いた内容の記憶に頼らないでください。「書き込んでから読み直す」サイクルがコンテキストの橋渡しになります。

このファイルはすべてのモードで不可欠です。シングルパスモードでは、成果物を生成する前に、具体的な調査結果（ファイルパス、関数名、行番号）を言語化することを強制します。マルチパスモードでは、パス間の引き継ぎ成果物にもなります。いずれの場合も、書き込みと読み直しのサイクルが調査の深さを担保する品質ゲートです。

Phase 1 完了ゲート（必須 — Phase 2 の前にここで停止）。 Phase 2 に進む前に、必ずこのゲートを実行してください。これは任意ではありません。quality/EXPLORATION.md をディスクから再読し、以下のすべてのチェックを実行してください。チェック後、EXPLORATION.md の末尾に ## Gate Self-Check セクションを追記し、各チェック番号（1〜12）ごとに PASS または FAIL と、一行の根拠メモを記載してください。いずれかのチェックが失敗した場合は、EXPLORATION.md を修正してからゲートを再実行してください。すべてのチェックが合格し、Gate Self-Check セクションがディスクに書き込まれるまで、Phase 2 に進まないでください。

よくあるゲート回避の失敗パターン： v1.3.43 のベンチマークでは、chi と zod の二つのリポジトリで、必要なセクションではなく「Architecture summary」「Behavioral contracts」「Repository and architecture map」などのセクション構造が完全に誤った EXPLORATION.md が生成されました。モデルはゲートのチェックを一度も実行せずに Phase 2 に直行し、バグをゼロ件しか生成できませんでした。EXPLORATION.md に、以下に列挙する正確なタイトルのセクションが含まれていない場合、それは非準拠であり、先に進む前に書き直す必要があります。

1. このファイルはディスク上に存在し、実質的な内容が少なくとも 120 行あります。
2. quality/PROGRESS.md が存在し、Phase 1 が完了としてマークされています。
3. Derived Requirements セクションには、具体的なファイルパスと関数名を含む REQ-NNN が少なくとも 1 件あります。抽象的なサブシステムの説明だけでは不十分です。
4. 完全に ## Open Exploration Findings という名前のセクションが存在し、それぞれファイルパスと行番号を伴う、具体的なバグの仮説または不審な発見を少なくとも 8 件含んでいます。これらはパターンを適用しただけの結果ではなく、ドメイン主導の調査から導かれたものでなければなりません。少なくとも 4 件は、異なるモジュールまたはサブシステムを参照している必要があります。
5. Open Exploration の深さチェック: ## Open Exploration Findings 内の少なくとも 3 件の発見は、2 つ以上の関数または 2 つ以上の具体的なコード位置にまたがる動作を追跡している必要があります。孤立した単一関数への疑いの羅列では不十分です。
6. 完全に ## Quality Risks という名前のセクションが存在し、優先度順に並べられた、ドメイン主導の障害シナリオを少なくとも 5 件含んでいます。各シナリオは次の条件を満たす必要があります：(a) 具体的な関数、ファイル、行番号を挙げること、(b) ドメイン固有のエッジケースまたは障害モードを説明すること、(c) コードが誤った動作を生じる理由を説明すること。これらは、このようなシステムで何が失敗しがちかというドメイン知識に基づくものでなければならず、コードの構造解析だけから導かれたものであってはなりません。コードが既に備えている防御的なパターン（コードが正しく行っていること）を列挙するセクションは、このゲートを満たしません。具体的な障害シナリオを伴わずにリスクのあるモジュールを列挙するセクションも、このゲートを満たしません。ライブラリが成熟しており、基本的なバグが起きにくいと結論づけるセクションも、このゲートを満たしません。
7. 完全に ## Pattern Applicability Matrix という名前のセクションが存在し、exploration_patterns.md の 6 つのパターンすべてを評価し、それぞれを FULL または SKIP とマークして、対象モジュールとコードベース固有の根拠を示しています。
8. 適用可能性マトリクスにおいて、FULL とマークされたパターンは 3 件以上 4 件以下（両端を含む）です。
9. タイトルが ## Pattern Deep Dive — で始まるセクションは 3 件以上 4 件以下（両端を含む）存在します。各セクションには、パターン名だけのプレースホルダーではなく、具体的なファイル:行番号の根拠が含まれている必要があります。件数は、マトリクス内の FULL パターンの数と一致しなければなりません。
10. パターンの深さチェック: 少なくとも 2 つのパターン深掘りセクションが、2 つ以上の関数にまたがるコードパスを追跡している必要があります。「ファイル:行番号の関数 X にはギャップがある」という記述は表面的な発見です。「ファイル:行番号の関数 X はファイル:行番号の関数 Y を呼び出し、Y は A を行うが B は行わない。両方を行う関数 Z と比較せよ」という記述は深い発見です。
11. 完全に ## Candidate Bugs for Phase 2 という名前のセクションが存在し、優先順位付けされたバグの仮説を少なくとも 4 件含んでいます。各仮説には、ファイル:行番号の参照、それを発見した段階（open exploration、quality risks、pattern のいずれか）、そしてコードレビューで何を確認すべきかが記載されている必要があります。
12. アンサンブルのバランスチェック: 少なくとも 2 件の候補バグは open exploration または quality risks に由来し、少なくとも 1 件はパターン深掘りに由来するか、パターン深掘りによって実質的に裏付けられている必要があります。これにより、ドメイン知識に基づく発見と構造解析に基づく発見の両方が Phase 2 に引き継がれることを保証します。

12 個のチェックすべてに合格し、## Gate Self-Check セクションが EXPLORATION.md にディスク上で書き込まれるまでは、Phase 2 を開始しないでください。Phase 1 は、コードベースを深く理解できる唯一の機会です。ここで満たし損ねた要件は、Phase 3 で見つけられないバグになります。時間をかけてください。

Phase 2 を開始しようとしているのに Gate Self-Check セクションを書いていないことに気づいた場合は、停止してください。 ゲートに戻って実行してください。この指示は、モデルが探索に自信を持っているときにゲートを飛ばしがちであり、まさにその自信こそがバグを見逃す瞬間だからこそ存在します。

フェーズ終了メッセージ（必須：Phase 1 の完了後にこのメッセージを出力し、その後停止すること）:

# Phase 1 Complete — Exploration

I've finished exploring the codebase and written my findings to `quality/EXPLORATION.md`.
[Summarize: how many candidate bugs, which subsystems explored, key risks identified.]

To continue to Phase 2 (Generate quality artifacts), say:

    Run quality playbook phase 2.

Or say "keep going" to continue automatically.

このメッセージを出力した後は停止してください。ユーザーが明示的に求めない限り、Phase 2 に進まないでください。

---

Phase 2: Quality Playbook の生成

v1.5.6 の計測： 今すぐ quality/run_state.jsonl に phase_start phase=2 を追記します。フェーズ終了時に、bin/run_state_lib.validate_phase_artifacts(quality_dir, 2) を呼び出して相互検証します。この関数は Generate の完全な契約（REQUIREMENTS.md、QUALITY.md、CONTRACTS.md、COVERAGE_MATRIX.md、COMPLETENESS_REPORT.md、RUN_CODE_REVIEW.md、RUN_INTEGRATION_TESTS.md、RUN_SPEC_AUDIT.md、RUN_TDD_TESTS.md、および空でない quality/test_functional.<ext> を1つ）を確認します。検証に合格した場合は、phase_end phase=2 を追記します。不合格の場合は、recoverable: true を指定した error イベントを追記し、不足しているアーティファクトの生成を再実行します。（BUG-014 の修正：v1.5.6 より前のこの注記では、リリースされなかった v1.5.5-design のトリアージモデルが参照されていました。）

このフェーズで必須の参照資料 — 続行する前に以下を読んでください：

• quality/EXPLORATION.md — Phase 1 の調査結果（アーキテクチャ、要件、ユースケース、パターン分析）
• references/requirements_pipeline.md — 要件導出のための5段階パイプライン
• references/defensive_patterns.md — 防御的コードを見つけるための grep パターン
• references/schema_mapping.md — スキーマ対応テストのフィールドマッピング形式
• references/constitution.md — QUALITY.md のテンプレート
• references/functional_tests.md — テスト構造とアンチパターン
• references/review_protocols.md — コードレビューと統合テストのテンプレート

Phase 2 のソース変更ガードレール（必須 — 即時停止）。 Phase 2 では quality/ 内にのみ書き込みます。対象リポジトリの quality/ ディレクトリ外にあるファイルは、作成、変更、削除しないでください。これには、以下に限定されませんが、AGENTS.md、CLAUDE.md、README.md、bin/**、.github/**、.claude/**、references/**、agents/**、SKILL.md、schemas.md、ソースコード、テストファイルが含まれます。対象リポジトリの AGENTS.md は Phase 6 の完了後にオーケストレーターが生成します。Phase 2 で AGENTS.md を書き込むと、オーケストレーターのソース未変更不変条件に抵触し、実行が中断されます。2026-04-30 の codex ブートストラップテストは、まさにこの理由で失敗しました。Phase 2 の LLM が既存の AGENTS.md を更新し（以前の SKILL.md の説明文に従ったため）、ソース未変更ゲートが変更を検出し、Phase 3 より前に実行が中断されました。生成したアーティファクトを quality/ の外に置くのが自然な場合は、代わりに quality/ 内に書き込み、最終処理時にオーケストレーターが移動またはコピーできるようにしてください。唯一の例外として許可されるのは、quality/ 内にある quality/PROGRESS.md です。

Phase 2 の開始ゲート（必須 — 即時停止）。 アーティファクトを生成する前に、ディスクから quality/EXPLORATION.md を読み込み、以下の条件がすべて満たされていることを確認してください（grep または検索を使用し、記憶に頼らないでください）。

1. quality/EXPLORATION.md は120行以上でなければなりません。短い場合は調査が不完全です
2. ## Open Exploration Findings — この見出しがそのまま存在すること
3. ## Quality Risks — この見出しがそのまま存在すること
4. ## Pattern Applicability Matrix — この見出しがそのまま存在すること
5. ## Pattern Deep Dive — で始まるセクションが3つ以上あること。この形式で存在すること
6. ## Candidate Bugs for Phase 2 — この見出しがそのまま存在すること
7. ## Gate Self-Check — この見出しが存在すること（Phase 1 のゲートが実行された証拠）
8. quality/PROGRESS.md が存在し、その Phase 1 の行に [x] が付いていること — Phase 1 が開始されただけでなく、完了した証拠
9. ## Open Exploration Findings セクションに、具体的なバグ仮説が8件以上含まれていること — ファイル名と行番号の引用がある行を数える
10. ## Open Exploration Findings の調査結果のうち、少なくとも3件が2つ以上の関数をまたいで動作をたどっていること — 複数箇所にわたる追跡を確認する
11. ## Pattern Applicability Matrix で FULL とマークされたパターンが3〜4件あること — FULL の項目を数える
12. パターンの詳細分析セクションのうち、少なくとも2つが2つ以上の関数にまたがるコードパスをたどっていること — 複数の関数にまたがる追跡を確認する
13. ## Candidate Bugs for Phase 2 に、オープンな調査結果またはリスクに由来するバグが2件以上、かつパターンの詳細分析に由来するバグが1件以上あること — 出典となるステージラベルを確認する ファイルが存在しない場合、120 行未満の場合、または以下の正確なセクションタイトルのいずれかが欠けている場合は、そこで停止して Phase 1 に戻ってください。異なる名前の「同等の」セクションで代用しようとしないでください。正確なタイトルが必要です。今すぐ EXPLORATION.md を作成してください。まずドメイン駆動のオープンな探索を行い、次にドメイン知識に関するリスク分析を行い、その後 references/exploration_patterns.md から 3～4 個のパターンを選んで深掘りします。EXPLORATION.md が Phase 1 の完了ゲートを通過するまで、Phase 2 に進まないでください。このチェックは、1 回の実行で Phase 1 のゲートが省略される事態を防ぐための最後の砦です。v1.3.43 では、2 つのリポジトリが両方のゲートを迂回し、バグが 0 件という結果になりました。

このフェーズでは、主な情報源として quality/EXPLORATION.md を使用してください。コードベースを一から再調査しないでください。探索結果には、以下のすべての成果物の基盤となるアーキテクチャマップ、導出した要件、ユースケース、リスク分析が記載されています。プロジェクトの内容を把握するためにソースファイルを読んでいることに気付いたら、代わりに EXPLORATION.md を確認してください。再調査はコンテキストを浪費し、Phase 1 の調査結果と Phase 2 で生成する内容の不整合を招きます。

それでは、Phase 2 の成果物を作成してください。上記の要件パイプラインで、REQUIREMENTS.md、CONTRACTS.md、COVERAGE_MATRIX.md、COMPLETENESS_REPORT.md が作成されています。以下の 7 つのファイルで一式が完成します。それぞれ、以下の構成に従い、詳細なガイダンスについては該当するリファレンスファイルを参照してください。

バージョンスタンプ（すべての生成ファイルで必須）。 プレイブックが生成するすべての Markdown ファイルは、タイトル見出しの直後に、次の帰属行を記載してください。

> Generated by [Quality Playbook](https://github.com/andrewstellman/quality-playbook) v1.5.3 — Andrew Stellman
> Date: YYYY-MM-DD · Project: <project name>

生成するすべてのコードファイル（テストファイル、スクリプト）は、コメントヘッダーで始めてください。

# Generated by Quality Playbook v1.5.6 — https://github.com/andrewstellman/quality-playbook
# Author: Andrew Stellman · Date: YYYY-MM-DD · Project: <project name>

言語に適したコメント構文（#、//、/* */ など）を使用してください。スタンプのバージョンは、このスキルのフロントマターにある metadata.version と一致させてください。このスタンプにより、生成された各成果物を、その作成元のツール、バージョン、実行にたどれるようになります。ファイルがリポジトリ外でメール送信されたり、チケットに添付されたり、レビューされたりする場合に不可欠です。各ファイルを書き込んだ日付ではなく、プレイブックの生成を開始した日付を使用してください。

スタンプの配置と例外：

• エンコーディングプラグマ（# -*- coding: utf-8 -*-）またはシバン（#!/usr/bin/env python）がある Python ファイルでは、スタンプコメントをプラグマ／シバンの前ではなく後に配置してください。スタンプが 2 行目より後になると SyntaxWarning が発生します。
• サイドカー JSON ファイル（tdd-results.json、integration-results.json）では、skill_version フィールドがすでにバージョンスタンプとして機能します。JSON はコメントに対応していないため、コメントを挿入しないでください。
• JUnit XML ファイルにはスタンプは不要です。これらはフレームワークによって生成されます。
• .patch ファイルには、差分本文にスタンプを挿入しないでください。git apply が失敗する原因になります。出所の記録は、周辺の成果物メタデータ（BUGS.md、tdd-results.json）で行ってください。

成果物の依存関係に関するルール：

• quality/RUN_CODE_REVIEW.md の Pass 2 は、安定した quality/REQUIREMENTS.md に依存します。要件が不十分だと、Pass 2 のレビューも不十分になります。要件数がコードの規模に対して少ないと思われる場合（コアモジュールあたり約 3～4 件未満）は、Pass 2 レポートの冒頭にその旨を記載してください。
• 機能テストは quality/REQUIREMENTS.md と quality/QUALITY.md に依存します。要件を調整した後は、test_functional.* が引き続きすべての要件を網羅していることを再確認してください。
• quality/RUN_SPEC_AUDIT.md は、要件、品質シナリオ、ドキュメントの検証に依存します。
• quality/COMPLETENESS_REPORT.md には 2 つの段階があります。ベースライン（レビュー前、判定セクションなし）と最終版（Phase 5 の照合作業後、正式な判定を記載）です。
• quality/PROGRESS.md は正式な状態管理ファイルです。後続の成果物を作成する前に更新してください。 なぜテストだけでなく、9つのファイルが必要なのですか？ テストはデグレードを検出しますが、新たな種類のバグを防ぐことはできません。品質の基本方針（QUALITY.md）は、コードを書き始める前に「正しい」とは何かを後続のセッションに伝えます。プロトコル（RUN_*.md）は、レビュー、統合テスト、仕様監査のための構造化された手順を提供し、AI が何をチェックするかに品質を委ねるのではなく、再現可能な結果を生み出します。これらのファイルが連携することで、それぞれが他を補強する品質システムが構築されます。QUALITY.md のシナリオは機能テストファイル内のテストに対応し、そのテストは統合プロトコルで検証され、さらに Council of Three によって監査されます。

v1.5.3 JSON マニフェストの規律（成果物を作成する前に読むこと）

フェーズ 2 では、派生レコードごとに 2 つの並行する表現を作成します。JSON マニフェスト（機械可読で、ゲートによる検証対象となる正本）と、Markdown 成果物（マニフェストから生成される、人間が読みやすい表現）です。一方を更新して、もう一方を更新しないフェーズスクリプトはバグです。

マニフェストの保存先は次のとおりです。

• quality/formal_docs_manifest.json — フェーズ 1 で bin/reference_docs_ingest.py が作成します。書き換えないでください。
• quality/requirements_manifest.json — schemas.md §6 に従った、REQ レコードの正本です。
• quality/use_cases_manifest.json — schemas.md §7 に従った、UC レコードの正本です。
• quality/bugs_manifest.json — schemas.md §8 に従った、BUG レコードの正本です。フェーズ 3/4/5 でバグを確認した後に作成します。
• quality/citation_semantic_check.json — フェーズ 4 の Council Layer 2 による判定結果です（以下のフェーズ 4 を参照）。

すべてのマニフェストは、schema_version、generated_at、トップレベルのレコード配列を含む §1.6 のラッパーに従います。レコード形式の 4 つのマニフェスト（formal_docs_manifest.json、requirements_manifest.json、use_cases_manifest.json、bugs_manifest.json）では、配列キーに records を使用します。

{
  "schema_version": "<from SKILL.md metadata.version>",
  "generated_at": "<ISO 8601 with explicit Z timezone>",
  "records": [ /* per-schema records, per schemas.md §4–§8 */ ]
}

例外 — citation_semantic_check.json では、schemas.md §9.1 に従い、records ではなく reviews を使用します。 ラッパーの形状は同じですが、配列キーが異なります。このファイル内のレコードは、REQ/UC/BUG レコードではなく、Council のレビュー項目です。citation_semantic_check.json に records を書き込もうとしている場合は、作業を中断し、schemas.md §9 を読み直してください。キーが間違っていると、ゲートはこのファイルをマニフェストラッパー違反（schemas.md §10 の不変条件 #13）として拒否します。

schema_version は、生成時点でこのスキルの metadata.version と一致していなければなりません。SKILL.md から読み取り、ハードコードしないでください。generated_at には datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z") を使用します。レコードの形状と不変条件は schemas.md で定義されています。このスキル内で再定義しないでください。quality_gate.py（フェーズ 5/6）は、マニフェストの各フィールドをそれらのスキーマと照合して検証します。

REQUIREMENTS.md の表示規約。 REQUIREMENTS.md は functional_section ごとに構成します。各セクションは、その機能領域の役割を説明する LLM 作成の簡潔な導入段落で始まり、その下に REQ を（REQ ID 順に）列挙します。ユースケースには formal_doc_refs を表示しますが、requirements[] は列挙しません。トレーサビリティは REQ → UC の一方向であり、逆方向の関係は REQ レコードを検索して表示時に導出します。

File 1: quality/QUALITY.md — 品質憲章

テンプレートと例の全文については、references/constitution.md を読んでください。

憲章は次の6つのセクションで構成されます。

1. 目的 — このプロジェクトにおける品質の意味を、Deming（品質は検査で作り込むのではなく、組み込むもの）、Juran（使用目的への適合性）、Crosby（品質にコストはかからない）の考え方に基づいて定義します。これらを具体的に当てはめてください。このシステムにとって「使用目的への適合性」とは何でしょうか。「テストに合格すること」ではなく、実際の運用要件を示します。
2. カバレッジ目標 — 各サブシステムと目標値を対応付けた表を作成し、実際のリスクを参照して根拠を示します。すべての目標に、具体的なシナリオに基づく「なぜ」が必要です。これがないと、将来のAIセッションで目標を引き下げる議論が起きます。
3. カバレッジの見せかけを防ぐ — 探索中に確認した内容を基に、このプロジェクト固有の偽のテスト例を示します。（理由：AIが生成するテストは、実際のバグを検出せずにカバレッジの数値だけを水増しすることがよくあります。たとえば、インポートが成功したこと、辞書にキーがあること、モックが設定どおりの値を返したことを検証するテストです。これを明示的に指摘することで、こうしたパターンを防げます。）
4. 目的適合性シナリオ — 中核となるセクションです。各シナリオでは、コードへの参照と検証方法を添えて、現実的な障害モードを記録します。中核モジュールごとに2件以上、標準的な規模のプロジェクトでは通常、合計8～10件を目指してください。小規模なプロジェクトでは少なく、複雑なプロジェクトでは多くなります。件数よりも質が重要です。実際のアーキテクチャ上の脆弱性を正確に捉えたシナリオは、一般的なシナリオ3件分よりも価値があります。（理由：カバレッジ率から分かるのは、コードがどれだけ実行されたかであり、正しく実行されたかではありません。カバレッジが95%のシステムでも、レコードがひそかに失われることがあります。目的適合性シナリオでは、「正しく動作する」とは具体的に何を意味するのかを、誰にも引き下げられない形で定義します。）
5. AIセッションの品質規律 — すべてのAIセッションが守るべきルール
6. 人間によるゲート — 人間の判断が必要な事項

シナリオの語り口が重要です。 「何が起きたか」は、抽象的な仕様ではなく、具体的な数量、連鎖的な影響、検出の難しさを含むアーキテクチャ上の脆弱性分析として記述してください。「save_state() にアトミックな名前変更の仕組みがないため、10,000件のバッチ処理中に書き込みが中断すると状態ファイルが破損し、次回の実行ではJSONDecodeErrorが発生して再開できなくなります。大規模な運用では、検出の仕組みがないまま1,693件以上のレコードがひそかに失われるリスクがあります。」こう記述すれば、AIセッションが基準を引き下げることはありません。類似システムに関する知見を使って現実的な障害シナリオを作成し、探索した実際のコードに基づいて具体化してください。シナリオは、コードの探索だけでなく、この種のシステムで何が問題になるかというドメイン知識からも導き出します。

すべてのシナリオの「検証方法」は、機能テストファイル内の少なくとも1つのテストに対応させてください。

ファイル 2：機能テスト

これが最も重要な成果物です。 詳細なガイドについては、references/functional_tests.mdをお読みください。

テストを、次の3つの論理的なグループ（クラス、describeブロック、モジュールなど、テストフレームワークで使用する形式）に整理します。

• 仕様要件 — テスト可能な仕様の各セクションにつき1つのテストを作成します。各テストのドキュメントには、検証する仕様要件を記載します。
• 適合性シナリオ — QUALITY.mdの各シナリオにつき1つのテストを作成します。1対1で対応させ、シナリオと一致する名前を付けます。
• 境界条件とエッジケース — ステップ5の各防御パターンにつき1つのテストを作成します。

重要なルール：

• 既存のインポートパターンに正確に合わせてください。 既存のテストでプロジェクトのモジュールをどのようにインポートしているかを読み、同じ方法にしてください。これを誤ると、すべてのテストが失敗します。
• 呼び出す前に、すべての関数のシグネチャを読んでください。 実際のdef行を確認し、パラメーター名、型、デフォルト値を読みます。プロジェクトの実データファイルを読み、データの形状を把握してください。関数のパラメーターやフィクスチャの構造を推測してはいけません。
• プレースホルダーテストは禁止です。 すべてのテストで、実際のプロジェクトコードをインポートして呼び出す必要があります。本文がpassだったり、アサーションが自明（assert isinstance(x, list)など）だったりするテストは削除してください。プロジェクトコードを実行しないテストは件数を水増しし、誤った安心感を生みます。
• テスト件数の目安 ＝（テスト可能な仕様セクション数）＋（QUALITY.mdのシナリオ数）＋（防御パターン数）。中規模のプロジェクト（ソースファイルが5〜15個）では、通常35〜50件になります。これを大幅に下回る場合は、要件の見落としか調査不足が考えられます。意味のあるテストであれば、大幅に上回っても問題ありません。件数合わせの水増しはしないでください。
• バリアント横断の目安：約30％ — プロジェクトが複数の入力型を扱う場合は、全バリアントを対象とするパラメーター化テストを約30％にすることを目指します。正確な割合よりも、横断的な特性がすべてのバリアントでテストされていることが重要です。
• 仕組みではなく結果をテストしてください。 コードの実装方法ではなく、仕様で定められた動作をアサートしてください。
• スキーマに適合する変更値を使用してください。 境界テストには、スキーマが受け入れる値（ステップ5bで確認）を使用し、スキーマが拒否する値は使わないでください。

ファイル 3：quality/RUN_CODE_REVIEW.md

テンプレートについては、**references/review_protocols.md**をお読みください。

コードレビュープロトコルは3回のパスで構成されます。各パスは独立して実行し、要件ドキュメント以外に共有コンテキストのない新しいセッションで行います。この明確な分離によって、構造レビューと要件ベースのレビューの相互干渉を防ぎます。

パス1 — 構造レビュー。 コードを読み、異常を見つけます。これは、あらゆるAIコードレビューツールがすでに得意としていることです。要件も重点領域も設けず、コードの正しさに関するモデル自身の知識だけを使います。次の必須ガードレールを守ってください。

• 行番号は必須です。行番号がなければ、指摘事項として扱いません。
• シグネチャだけでなく、関数本体も読みます。
• 判断に迷った場合は、BUGではなくQUESTIONとして報告します。
• 存在しないと主張する前に、grepで検索します。
• スタイル変更は提案しないでください。誤りがあるものだけを指摘します。

パス1で最低限確認すべき領域（それぞれを明示的に扱うこと）：

1. 入力検証と境界処理 — 外部データまたは呼び出し元が提供するデータがコードに入るすべての信頼境界を確認してください。すべての文字列パーサー、列挙値の検索、バイナリ形式パーサーは、有効なトークンと共通の有効なプレフィックスを持ちながら追加の文字を含む入力を必ず拒否しなければなりません。

2. リソースのライフサイクル — 割り当て、参照カウント管理、エラーパスでのクリーンアップ、失敗時のロック解放、ファイルディスクリプタ/ハンドルの寿命。参照またはリソースを取得するすべての関数は、早期終了するすべての経路で解放しなければならず、またはリソースを取得する前にすべての検証を完了しなければなりません。

3. 並行性と状態管理 — ロック順序、アトミック操作の正しさ（共有状態ワードへのすべてのアトミックな変更は読み取り・変更・書き込みのセマンティクスを使用し、意図した変更の範囲外のビットを保持しなければなりません）、状態遷移の完全性（すべての消費者ですべての状態が処理されていること）。

4. 単位とエンコーディングの正しさ — ハードウェア、プロトコル構造体、またはユーザー入力から読み取られ、定義された単位を持つすべてのフィールドは、計算や比較に使用する前に正しく変換しなければなりません。

5. 列挙と許可リストの網羅性 — 関数がswitch/case、match、if-else チェーン、または名前付き定数の集合（機能ビット、列挙値、イベント種別、コマンドコード、権限フラグ）を処理するための分岐構造を使用している場合、機械的な列挙チェックを実施してください：

   (a) リスト A（コードからの抽出）: この関数に対する quality/mechanical/<function>_cases.txt アーティファクトが存在する場合は、それをコード側の正式なリストとして使用し、手作業で再抽出しないでください。機械的アーティファクトが存在しない場合は、コードに実際に存在するすべての分岐/case ラベルを抽出してください。それぞれを正確な行番号付きで列挙してください：「line 3511: case VIRTIO_RING_F_INDIRECT_DESC」、「line 3513: case VIRTIO_RING_F_EVENT_IDX」など。このリストはコードからのみ抽出してください — REQUIREMENTS.md、CONTRACTS.md、またはその他の生成アーティファクトからコピーしないでください。 case ラベルの行番号を示せない場合、そのラベルは存在しないものとみなします。

   (b) リスト B（仕様からの抽出）: 関連するヘッダー、列挙型、または仕様で定義されており、処理されるべきすべての定数を列挙してください。

   (c) 差分: 2つのリストを比較してください。リスト B の各定数について、「FOUND (line NNN)」または「NOT IN CODE」とマークしてください。定義されているが処理されていない定数があれば報告してください。

   この2リストの比較を行わずに、許可リストが「すべての値を網羅している」または「サポートされるビットを保持している」と断言しないでください。 AI モデルは switch/case 構造について網羅性を幻覚的に主張する傾向が強く、関数を見て他所で定義された定数を確認し、各 case ラベルを検証せずに網羅されていると思い込みます。最も危険なのは、上流のアーティファクト（REQUIREMENTS.md など）が定数の存在を主張している内容をコピーし、コードから抽出しないことです。v1.3.17 では、コードレビューの「case ラベルが存在するもの」リストが要件リストと一字一句同一であり、コピーされたもので抽出されたものではないことが判明しました。行番号付きのラベルごとの機械的チェックがその解決策です。

これら5つの領域は、Pass 1 レポートにラベル付きの小節として必ず含めてください。プロジェクトに意味のある並行性がない場合は、その旨を明示し、理由を記載してください。セクションを省略しないでください。必要に応じて、これら5つ以外のプロジェクト固有の精査領域を追加してください。

Pass 1 は、実際の欠陥の約65%を検出します：競合状態、null ポインタの危険、リソースリーク、オフバイワンエラー、型の不一致など、コード上で視認できる構造的な問題です。

Pass 2 — 要件検証。 フェーズ1のステップ7で導出された各テスト可能な要件について、コードがその要件を満たしているかを確認してください。各要件について、それを満たすコードを示すか、満たしていない理由を具体的に説明してください。これは純粋な検証パスです。レビュアーの唯一の役割は「コードはこの要件を満たしているか？」に答えることです。一般的なレビューではありません。他のバグを探すものでもありません。検証のみを行ってください。 最小限の根拠ルール: Pass 2 では、要件ごとに少なくとも 1 つのコード位置（file:line または file:function）を引用しなければなりません。「REQ-003 から REQ-012 — 当該パス中に確認したクライアントのパスによって満たされる」のように、要件ごとのコード引用を伴わない包括的な充足の主張は、Pass 2 の要件を満たしません。2 つまたは 3 つの要件が同じ関数によって満たされる場合は、その関数を一度だけ引用し、対象の要件を個別に列挙してください。ただし、各要件は未検証の範囲の一部としてではなく、それぞれ個別の SATISFIED/VIOLATED の判定を持つ必要があります。1 つの引用の下に 3 つを超える要件がまとめられている場合、その検証が表面的であったことを示す兆候です。目的はトレーサビリティです。Pass 2 を読むレビュアーは、コードベース全体を読み直すことなく、任意の単一の要件から、それを満たすコードまでの証跡をたどれなければなりません。

列挙の網羅性の主張には機械的な証明が必要です。 ホワイトリスト、ルックアップテーブル、機能ビットセット、ハンドラーレジストリ、あるいは「すべての X は Y によってカバーされる」という形式の主張を含む要件を評価する場合、レビュアーは Pass 1 のスクラッティニー領域 5 にある 2 リストの列挙チェックを実行しなければなりません。すなわち、コードからすべての項目を（行番号付きで）抽出し、仕様からすべての項目を抽出して、両者を比較します。コード側のリストは、ソースから新たに抽出しなければなりません。REQUIREMENTS.md、CONTRACTS.md、コードレビュー用プロンプト、その他の生成された成果物のリストを再利用してはなりません。 コード側のリストが要件リストと一字一句一致する場合、そのリストはコードから抽出されたのではなく複写された兆候であり、チェックをやり直さなければなりません。

関数を読んで「すべてを処理していると思う」という理由だけで、そのような要件を SATISFIED とマークしないでください。これは、このルールが防ごうとしている特定の幻覚のパターンです。例：ある要件が「トランスポートの機能ホワイトリストは、サポートされるすべてのリング機能を保持しなければならない」と定めているとします。レビュアーは vring_transport_features() を読み、switch/case があることを確認します。正しいチェックは、各 case ラベルを行番号付きで抽出し（line 3511: INDIRECT_DESC、line 3513: EVENT_IDX、…、line 3527: default）、次にヘッダーの定数を列挙して、両者を比較することです。誤った判断は「ホワイトリストはサポートされるビットを保持しており、VIRTIO_F_RING_RESET を含む」と述べることであり、RING_RESET が実際に case ラベルとして現れるかを確認しないことです。この失敗パターンは複数のバージョンで実際に観察されています。モデルは switch に存在しない定数のカバレッジを主張しており、v1.3.17 では、コードレビューの「case ラベルが存在する」リストが、コードから抽出されたのではなく要件から複写されたため、3 人の独立した仕様監査者が誤った主張を引き継ぎました。

Pass 2 は個々の要件への違反を検出します。すなわち、コードが仕様の定める動作をしていない場合です。これは、そこにあるコードが正しいために構造レビューでは見逃されるバグを発見します。バグは欠けている部分、または仕様と一致しない部分にあります。

Pass 3 — 要件間の整合性。 同じフィールド、定数、範囲、またはセキュリティポリシーを参照する要件のペアを比較します。各ペアについて、それらの制約が相互に矛盾しないことを検証してください。数値範囲はビット幅と一致しているか。セキュリティポリシーはすべての接続の種類に伝播しているか。あるファイルの検証境界は、別のファイルのエンコーディング上の上限と一致しているか。

Pass 3 は、2 つのそれぞれ正しいコードが共有する制約について互いに食い違う矛盾を検出します。これらのバグは、各要件が個別には満たされているため、構造レビューにも要件ごとの検証にも見えません。バグは両者を比較したときにのみ現れます。これは、ファイルをまたぐ算術のバグや、セキュリティ設定がすべての接続経路に伝播していない設計上のギャップを捕捉する pass です。 ソースコードの境界に関するルール： プレイブックはquality/ディレクトリ外のファイルを決して変更してはなりません。すべてのソースツリーへの変更（バグ修正や、プロジェクト独自のテストスイートへのテスト追加）は、quality/patches/以下に保存するgit diff形式のパッチファイルとして表現してください。これにより、元のソースツリーは変更されず、パッチはレビューおよび取り消しが可能になり、プレイブックの監査結果を監査対象のコードから明確に分離できます。

BUGS.md： すべてのレビューと監査フェーズの完了後、quality/BUGS.mdを生成してください。確認済みの各バグについて、再現方法の詳細をすべて記載した統合バグレポートです。各バグには、バグ ID、発見元（コードレビューまたは仕様監査）、ファイル:行、説明、重大度、最小限の再現シナリオ（バグを引き起こす入力または手順）、期待される動作と実際の動作、回帰テストおよび提案する修正パッチへの参照、さらに仕様上の根拠を含めてください。

BUGS.md — v1.5.3 BUG レコードのフィールド（schemas.md §8）。 各BUGS.md項目（および各quality/writeups/BUG-NNN.md）は、quality/bugs_manifest.jsonに記録されるBUGレコードに対応します。上記の説明に関する規約に加え、すべてのBUGには次の項目が必要です。

• id — 3桁の数字をゼロ埋めした連番BUG-NNN。
• divergence_description — 文書化された意図とコードの動作との乖離を1段落で要約したもの。
• documented_intent — REQまたは仕様の文言からの直接引用、またはそれに近い言い換え。
• code_behavior — コードの実際の動作。file:lineの参照を含めてください。
• disposition — schemas.md §3.2に定める列挙値：code-fix | spec-fix | upstream-spec-issue | mis-read | deferred。必須であり、nullは不可です。新しい値を勝手に追加しないでください。
• disposition_rationale — 隣接する別の選択肢ではなく、なぜこの処置を選んだのかを説明する1段落（例：なぜupstream-spec-issueではなくcode-fixなのか、またはなぜmis-readではなくspec-fixなのか）。定型的な説明（「仕様にそう書かれているのでコードが間違っている」）ではCouncilレビューを通過できません。
• req_id — 単一のREQを指定します。乖離が複数のREQに関係するように見える場合は、根本原因を共有するバグをREQごとに分け、disposition_rationale内で相互参照してください（schemas.md §8.1）。1つの項目に複数のREQ IDを詰め込まないでください。
• proposed_fix — disposition == "mis-read"の場合を除き必須です。fix_type ∈ {code, both}の場合はパッチ形式、fix_type == "spec"の場合はテキストの変更案としてください。mis-readレコードではこのフィールドは任意です。記載する場合、実際に反映する変更ではなく、再読内容（プレイブックが何を読み違え、正しい解釈をどのように確認したか）を記載してください。
• fix_type — schemas.md §3.4に定める列挙値：code | spec | both。disposition × fix_typeの組み合わせは、§3.4の許容組み合わせ表で制約されています（§10の不変条件#12で適用）。許可されない組み合わせ：code-fix × spec、spec-fix × code、upstream-spec-issue × code、mis-read × both。レコードを作成する前に組み合わせ表を確認してください。不許可の組み合わせはゲートで拒否されます。

乖離の記述方法（writeupの文体、schemas.md v1.5.3）。 欠陥とは、文書化された意図とコード実装との乖離であり、コードが「良い」かどうかの評価ではありません。writeupの冒頭のセクション（Summary、Spec reference、The code）は、divergence_description、documented_intent、code_behaviorを人が読める形で表したものです。物語形式ではなく、左右に並べた差分として読めるように記述してください。読者がREQ／仕様の文言とコードの動作を並べて確認し、その差をすぐに把握できるようにしてください。対立的な口調（「コードがずさんだ」）や、タイトルでの価値判断（「ずさんなトレーラー処理」）は、この記述方針に反します。バグとは乖離を観察したものであり、非難ではありません。上流のメンテナーは、批判に対してコードを擁護するのではなく、処置（code-fix、spec-fix、upstream-spec-issue）に沿って検討します。 バグの確認に十分な証拠とは（重要）。 特定の動作違反を示すコードパスの追跡は、バグを確認するのに十分な証拠です。候補から確認済みに昇格させるために、リクエストを実行した証拠、実行中のテスト、または統合レベルでの再現は必要ありません。具体的には、次のとおりです。

• 関数 A が関数 B を呼び出し、B が X を実行するものの、本来は Y を実行すべきだと示すコードパスの追跡（file:line の参照を含む）— 確認に十分。
• 列挙内容を比較して特定したケース／分岐の欠落（仕様では X を処理すべきとされているが、コードには X の処理がない）— 確認に十分。
• Pass 2 で特定した要件違反で、コードが指定された動作を実装していないことが明らかなもの — 確認に十分。
• 入力から特定のコードを経て誤った出力に至るまで追跡できる、ドメイン知識に基づく指摘 — 確認に十分。

「リクエストを実行した証拠」を要求したり、「実装上の選択と仕様の欠落を区別するには実行時テストが必要」として指摘の判断を先送りしたりしないでください。仕様またはドキュメントで動作が X と定められており、コードパスを追跡することでコードが Y を生成すると明らかにできるなら、それは確認済みのバグであり、実行時検証を待つ候補ではありません。回帰テストと TDD のプロトコルは、確認の前提条件ではなく、確認後に実行時の証拠を得るためにあります。

このルールが存在する理由： v1.3.43 の javalin ベンチマークでは、コードレビューとトリアージの両方が、コードパスの追跡と要件違反によって正当性を示せる候補バグを 4 件特定しましたが、「最も確度の高い項目でも、リクエストを実行した証拠が必要」として、すべてを降格させました。その結果、以前のバージョンで 5 件のバグが見つかっていたコードベースから、確認済みのバグが 1 件も出ませんでした。確認前に実行時の証明を求めるという、証拠の基準を逆に設定していました。プレイブックの設計は、先に確認し、TDD で証明することです。

重大度の調整： 認証情報の漏えい、認証のバイパス、インジェクションに分類されるバグは、評価された可能性にかかわらず、常に重大度を高くしてください。信頼境界を越えた認証ヘッダーの露出（クロスドメインへのリダイレクトなど）は、認証情報の漏えいに該当します。セキュリティに関わる重大度の判断に迷う場合は、高く設定してください。

開発用スキャフォールディングの除外（セキュリティに関する指摘を確認する前に適用する初期フィルター）。 上記の重大度調整ルールでは、認証情報の漏えいや認証のバイパスに関する指摘は自動的に重大度が引き上げられます。そのような指摘をバグとして確認する前に、次の機械的なテストを適用してください。

精査対象の値に、デプロイ担当者へ置き換えを明示する自己説明的な目印（change-me、replace-me、placeholder、example、default、dummy、TODO、FIXME、your-secret-here、insert-、set-this- などの語）が含まれていますか？

含まれている場合：これはバグではありません。 記録しないでください。自己説明的な開発用プレースホルダーは不具合ではなくスキャフォールディングです。設定がなくても、プロジェクトをローカルでビルドして実行できるようにするために存在します。同じ考え方は、テスト用フィクスチャ、設定例、シードデータ、および名前や周辺のコメントで本番用ではないと明示されている値にも当てはまります。

これは、確認時に最も明白な誤検知を除外する初期フィルターです。Phase 5 のチャレンジゲート（references/challenge_gate.md を参照）は、より広範な仕組みであり、ドキュメント化された機能の欠落、WHY 注釈付きの設計上の判断、および監査担当者が「期待される動作」を作り上げた指摘など、より微妙なケースを検出します。スキャフォールディング除外を通過したセキュリティ関連の指摘も、自動トリガーパターンに該当する場合は、Phase 5 で引き続きチャレンジゲートの対象になります。 仕様の根拠（バグごとに必須）： 期待される動作を定めている、具体的なドキュメントの記述を引用してください。収集したドキュメントのファイル名、セクション／ページ、およびそこで定義されている動作上の契約を記載します。収集したドキュメントに該当する記述がない場合は、プロジェクト独自のコメント、README、API ドキュメントで定義されていないか確認してください。期待される動作を定めるドキュメントが存在しない場合、そのバグは「仕様違反」ではなく「コードの不整合」に分類し、重大度評価にその旨を記載してください。仕様違反はコードの不整合よりも重大な指摘です。コードが単に誤っているように見えるというだけでなく、権威ある情報源にコードが反していることを意味します。上流に報告する際、この違いは重要です。「あなたのコードは独自の仕様の X.Y 節に違反している」という報告と、「これはバグかもしれません」という報告では、メンテナーの対応が異なるためです。

パッチファイル（確認済みのバグごとに必須）： 確認済みのバグごとに、次のファイルを生成してください。

• quality/patches/BUG-NNN-regression-test.patch — バグを実証するテストを追加する git diff です。このパッチは必須であり、任意ではありません。 修正方法に関する意見に左右されず、バグの存在を示す最も強力な証拠となります。回帰テスト用パッチのない確認済みバグは不完全と見なされ、quality_gate.py は FAIL になります。バグを確認したら、次のバグに進む前に直ちにこのパッチを生成してください。
• quality/patches/BUG-NNN-fix.patch（任意ですが、強く推奨）— 提案する修正を含む git diff です。修正が 1 行または数行の変更で済む場合（例：ケースラベルの追加、引数の修正など）は、修正パッチを生成してください。手間が少なく、効果が大きいためです。

パッチファイルの生成方法。 git diff 形式を使用してください。最も簡単な方法は、パッチの内容を統一差分として直接記述することです。回帰テスト用パッチの例：

--- /dev/null
+++ b/quality/test_regression_virtio.c
@@ -0,0 +1,15 @@
+// Generated by Quality Playbook v1.5.6
+// Regression test for BUG-004: VIRTIO_F_RING_RESET missing from vring_transport_features()
+#include <assert.h>
+#include <string.h>
+...

既存のソースファイルを変更する修正パッチでは、正しい行オフセットを指定して --- a/path / +++ b/path 形式を使用してください。正確な行オフセットを特定できない場合は、パッチの内容を生成し、「オフセットは概算」と注記してください。概算のパッチでも、パッチがないより有用です。

パッチは、元のソースツリーに対して git apply で問題なく適用できなければなりません。ソースツリーを直接変更しないでください。

パッチ検証ゲート（必須）。 修正パッチを伴うバグを確認済みとする前に、次のゲートを実行してください。

1. 適用テスト： git apply --check quality/patches/BUG-NNN-regression-test.patch — 終了コードが 0 でなければなりません。
2. 適用テスト＋修正： git apply --check quality/patches/BUG-NNN-fix.patch — 終了コードが 0 でなければなりません（回帰テスト適用後のツリーではなく、クリーンなツリーに対してテストします。ただし、修正パッチが回帰テストに依存する場合を除きます）。
3. コンパイルチェック： 両方のパッチを適用した後、プロジェクトのビルド／コンパイルコマンドを実行します（例：go build ./...、mvn compile、cargo check、tsc --noEmit）。成功しなければなりません。

手順 3 での一時的なワークツリー。 手順 1～2 では --check を使うため、変更は加えられません。手順 3 ではパッチを実際に適用してコンパイルする必要があり、ソースツリーが変更されます。ソースコード境界ルール（「quality/ 外のファイルは変更しないこと」）を守るため、手順 3 は破棄可能なワークツリーで実行してください。

git worktree add /tmp/qpb-patch-check HEAD --quiet
cd /tmp/qpb-patch-check
git apply quality/patches/BUG-NNN-regression-test.patch quality/patches/BUG-NNN-fix.patch
<compile command>
cd -
git worktree remove /tmp/qpb-patch-check --force

git worktree が使用できない場合（浅いクローンや detached HEAD など）は、代わりに git stash && git apply ... && <compile> && git checkout . && git stash pop を使用するか、--check のみで検証し、その制約を注記してください。 インタープリター言語のコンパイルチェック。 コンパイルコマンドはエコシステムによって異なります。

• Go： go build ./...
• Rust： cargo check
• Java/Kotlin（Maven）： mvn compile -q
• Java/Kotlin（Gradle）： ./gradlew compileJava compileTestJava -q
• TypeScript： tsc --noEmit
• Python： 構文チェックには python -m py_compile <changed_files> を実行し、その後、インポート／検出の検証には pytest --collect-only -q を実行します
• JavaScript（Node.js）： 構文チェックには node --check <changed_files> を実行します。プロジェクトで ESLint を使用している場合は、構造上の問題を確認するために npx eslint <changed_files> を実行します
• JavaScript（Mocha/Jest）： 検出専用モードで対象のテストを実行し（mocha --dry-run または jest --listTests）、エラーなく読み込めることを確認します

プロジェクトの言語でコンパイル／構文チェックを実施できない場合は、その旨をパッチの記録に記載し、TDD のレッドフェーズで構文エラーを検出します。

いずれかの手順が失敗した場合は、バグが確認済みとして記録する前にパッチを修正してください。適用できない壊れたパッチによるバグは、確認済みのバグではなく、根拠が壊れた仮説です。適用できないパッチでは TDD のレッド・グリーンサイクルを実施できません。また、適用できないパッチでバグを報告すると、上流のメンテナーからの信頼を損ないます。よくあるパッチの失敗には、ハンクの切り詰め（閉じ波括弧の欠落）、行オフセットの誤り（クリーンなツリーではなく変更済みのツリーを基にパッチを生成）、生成したテストコードの構文エラーがあります。

パッチ修正の要件。 確認済みの各バグには、次のいずれかが必要です。

• 上記の検証ゲートを通過する quality/patches/BUG-NNN-fix.patch、または
• 修正パッチを提供しない理由の明示的な説明を BUGS.md に記載すること（例：「修正にはパッチの範囲を超えるアーキテクチャ上の変更が必要」「複数の妥当な修正方法があるため、メンテナーの判断に委ねる」「バグは上流の依存関係にある」）。

回帰テストがあっても、修正パッチもその理由の説明もないバグは未完成です。回帰テストはバグの存在を証明し、修正パッチ（またはパッチがない理由の説明）が証拠の連鎖を完成させます。修正パッチのないバグは「TDD 検証済み（FAIL→PASS）」のステータスにはできず、修正が提供されるまでは「確認済み・未解決（xfail）」のままです。

TDD 検証サイクル： 修正パッチがある確認済みの各バグについて、レッド・グリーンの TDD サイクル（パッチ未適用のコードではテストが失敗し、修正後は成功すること）を実施する必要があります。これはコードレビュー中にその場で行うのではなく、quality/RUN_TDD_TESTS.md のプロトコル（ファイル 7）を通じて実行します。このプロトコルでは、収集したドキュメントにすべてのアサーションメッセージ、変数名、コメントの根拠をたどれる、仕様に基づいたテストを生成します。

3 回すべてのレビューが完了したら： 調査結果をまとめます。確認済みの各バグを再現する回帰テストを quality/test_regression.* に記述します。test_functional.* と同じテストフレームワークを使用してください。機能テストが pytest を使用している場合、回帰テストも pytest（@pytest.mark.xfail(strict=True) を使用）を使用します。機能テストが unittest を使用している場合、回帰テストも unittest（@unittest.expectedFailure を使用）を使用します。結果は確認テーブル（BUG CONFIRMED / FALSE POSITIVE / NEEDS INVESTIGATION）として報告してください。3 パスの完全なテンプレートと回帰テストのプロトコルについては、references/review_protocols.md を参照してください。

回帰テストのスキップガード（必須）。 quality/test_regression.* のすべての回帰テストには、パッチ未適用のコードでテストスイート全体を実行しても予期しない失敗が発生しないよう、スキップ／xfail ガードを含める必要があります。このガードは、フレームワークで最も早い構文上のガードでなければなりません。慣用的な場合はデコレーターまたはアノテーションを使い、それ以外の場合はテスト本体の最初の実行可能な行に配置します。言語に適した方法を使用してください。

• Python (pytest): @pytest.mark.xfail(strict=True, reason="BUG-NNN: [description]") — def test_...(): のデコレーターとして上に配置します（関数本体の内側には置きません）。バグが存在する場合、テストは失敗して XFAIL（想定どおりの失敗）になります。バグが修正されたのにマーカーを削除していない場合、テストは成功して XPASS になり、strict モードではこれが失敗扱いになります。これはガードを削除すべきであることを知らせる仕組みです。
• Python (unittest): @unittest.expectedFailure — テストメソッドの上に置くデコレーターです。
• Go: t.Skip("BUG-NNN: [description] — unskip after applying quality/patches/BUG-NNN-fix.patch") — テスト関数内の最初の行に置きます。注意：Go の t.Skip はテストを完全に隠します（FAIL ではなく SKIP と報告されます）。これは Python の xfail より弱い証拠です。これは Go のテストプリミティブの既知の制限です。
• Java (JUnit 5): @Disabled("BUG-NNN: [description]") — テストメソッドの上に置くアノテーションです。
• Rust: テスト関数に #[ignore] 属性を付けます（デフォルトのテストスイートで実行しないための標準的な仕組みです）。#[should_panic] はパニックとして現れるバグにのみ使用し、compile_fail の doctest アノテーションはコンパイル時のバグにのみ使用してください。
• TypeScript/JavaScript (Jest): test.failing("BUG-NNN: [description]", () => { ... })
• TypeScript/JavaScript (Vitest): test.fails("BUG-NNN: [description]", () => { ... })
• JavaScript (Mocha): it.skip("BUG-NNN: [description]", () => { ... })、または条件付きスキップのためにテスト本体内で this.skip() を使用します。

バグが修正された場合（修正パッチを恒久的に適用した場合）、スキップガードを削除し、BUG トラッカーのクローズ状態を「confirmed open」から「fixed (test passes)」に更新してください。スキップガードのメッセージには、スキップされたテストに遭遇した人が解決方法を正確に把握できるよう、バグ ID と修正パッチのパスを記載する必要があります。

ソースインスペクションテストは必ず実行すること（run=False は使用しない）。 ソースファイルの構造を検証する回帰テスト（関数本体内の文字列の存在確認、case ラベルの存在確認、enum の抽出、生成コードの形状チェックなど）は、安全で決定的かつ高速です。これらはリポジトリ内のファイルを読み取り、文字列の照合を行います。このようなテストには、実行を有効にした @pytest.mark.xfail(strict=True) を使用してください。テストが外部状態を変更する、ハングする、または利用できないインフラを必要とする場合を除き、run=False を使用しないでください。run=False のソースインスペクションテストは最悪の状態です。正しいチェックは存在しているのに、何も動作しません。v1.3.18 では、BUG-004 の回帰テスト（test_bug_004_transport_feature_whitelist_keeps_ring_reset）に正しいアサーション assert "case VIRTIO_F_RING_RESET:" in func が含まれていましたが、run=False が設定されていました。そのためテストは一度も実行されず、アサーションも発火せず、テストスイートが「成功」しているにもかかわらずバグは検出されないままでした。xfail(strict=True) のテストが実際に実行されて失敗すると、テストスイートはそれを XFAIL（想定された失敗）として報告します。これは正しい動作であり、スイートの失敗ではありません。 スキップガードを使った TDD のレッド／グリーンの実行。 TDD の検証サイクル中、テストを実際に実行するため、レッドフェーズとグリーンフェーズでは一時的にスキップガードを回避する必要があります。プロトコルでは、エージェントに次のように指示してください。

• レッドフェーズ（絶対にスキップしない）： スキップ／xfail ガードを削除または無効にしてから、パッチ未適用のコードに対してテストを実行します。テストは失敗しなければなりません。結果を記録した後、ガードを再度有効にします。修正パッチがない場合でも、確認済みのバグすべてでレッドフェーズは必須です。 レッドフェーズの証拠がないバグは未検証です。失敗するレッド実行を行わずに verdict: "skipped" と記録してはいけません。文書化された理由（コンパイル失敗、環境を利用できないなど）でレッドフェーズを実行できない場合は、red_phase: "error" と記録し、notes に説明を記載します。
• グリーンフェーズ： ガードを削除または無効にし、修正パッチを適用してテストを実行します。テストは合格しなければなりません。修正を取り消す場合は、ガードを再度有効にします。修正パッチがない場合は、green_phase: "skipped" と記録します。ただし、レッドフェーズは必ず実行してください。
• TDD サイクル後： コミット済みの回帰テストファイルでは、ガードを有効なままにします。ガードを恒久的に削除するのは、修正がソースツリーにマージされたときだけです。

TDD 実行の徹底（必須）。 回帰テストは、パッチファイルとして生成するだけでなく、TDD の検証サイクル中に実際に実行しなければなりません。確認済みのバグごとに、レッドフェーズのテスト実行結果を記録したログファイルを quality/results/BUG-NNN.red.log に作成する必要があります。修正パッチがある場合、グリーンフェーズのログファイルを quality/results/BUG-NNN.green.log に作成する必要があります。各ログファイルの1行目には、ステータスタグ RED（テストが想定どおり失敗）、GREEN（修正後にテストが合格）、NOT_RUN（説明を添えてテストを実行できなかった）、または ERROR（説明を添えてテストインフラストラクチャでエラーが発生）を記載します。

言語に応じたテスト実行コマンド。 回帰テストの実行には、プロジェクト標準のテストランナーを使用します。プロジェクトの言語を判別し、適切なコマンドを使用してください。

• Go： go test -v -run TestBugNNN ./path/to/package
• Python（pytest）： python -m pytest -xvs quality/test_regression.py::test_bug_nnn
• Python（unittest）： python -m unittest quality.test_regression.TestRegression.test_bug_nnn
• Java（Maven + JUnit）： mvn test -pl module -Dtest=RegressionTest#testBugNnn
• Java（Gradle + JUnit）： ./gradlew test --tests RegressionTest.testBugNnn
• Rust： cargo test bug_nnn -- --nocapture
• TypeScript/JavaScript（Jest）： npx jest --verbose --testNamePattern="BUG-NNN"
• TypeScript/JavaScript（Vitest）： npx vitest run --reporter=verbose --testNamePattern="BUG-NNN"
• C（カーネル／make ベース）： シェルスクリプトによるソース検査テスト（ソースファイルに対する grep/awk）。スクリプトの出力をログに記録します。

プロジェクトで上記にない言語やテストフレームワークを使用している場合は、プロジェクトですでに使用されているテストランナーを利用し（Makefile、package.json、build.gradle、Cargo.toml、go.mod、setup.py、pyproject.toml などを確認）、パターンを適宜調整してください。テストランナーを利用できない場合、または言語ランタイムがインストールされていない場合は、理由を添えて NOT_RUN と記録します。ログファイルを省略してはいけません。

ログの記録形式。 各 BUG-NNN.red.log および BUG-NNN.green.log は、次の形式に従う必要があります。

RED
--- Test output for BUG-NNN red phase ---
Command: [exact command run]
Exit code: [exit code]
[full stdout/stderr from test execution]

1行目のステータスタグ（RED、GREEN、NOT_RUN、ERROR）は機械可読です。quality_gate.py はタグの有無を確認します。テストランナーを利用できない場合（たとえば、カーネルのビルド環境がない C プロジェクトなど）は、NOT_RUN を使用できます。ただし、テストを実行できなかった理由を記載したログファイルは必ず作成してください。

そのまま実行できる TDD ログのテンプレート。 確認済みの BUG-NNN ごとに、次の手順を実行します（上記の表に従い、プロジェクトの言語に合わせてテストコマンドを調整してください）。

# ── Red phase: revert fix, run test, expect FAIL ──
git apply -R quality/patches/BUG-NNN-fix.patch 2>/dev/null   # revert fix if applied
TEST_CMD="python -m pytest -xvs quality/test_regression.py::test_bug_nnn"  # adapt per language
OUTPUT=$($TEST_CMD 2>&1); EXIT=$?
printf 'RED\n--- Test output for BUG-NNN red phase ---\nCommand: %s\nExit code: %d\n%s\n' \
  "$TEST_CMD" "$EXIT" "$OUTPUT" > quality/results/BUG-NNN.red.log

# ── Green phase: apply fix, run test, expect PASS ──
git apply quality/patches/BUG-NNN-fix.patch
OUTPUT=$($TEST_CMD 2>&1); EXIT=$?
printf 'GREEN\n--- Test output for BUG-NNN green phase ---\nCommand: %s\nExit code: %d\n%s\n' \
  "$TEST_CMD" "$EXIT" "$OUTPUT" > quality/results/BUG-NNN.green.log

すべての確定したバグについて、これを実行してください。テストランナーが利用できない場合は、1行目に NOT_RUN と説明を記載したログファイルを作成してください。この手順を省略しないでください。ログが欠けている場合、フェーズ5の TDD Log Closure Gate で完了がブロックされます。

TDD 実行ゲート。 フェーズ5の最終ゲートの前に、quality/BUGS.md 内のすべての確定バグについて、対応する quality/results/BUG-NNN.red.log が存在することを確認してください。赤フェーズのログがないバグは未完了とみなします。その場合、回帰テストパッチは存在しても、そのバグを実際に検出できることが証明されていません。このゲートは、v1.3.45 のベンチマークで、ほとんどのリポジトリが回帰テストパッチを生成するものの実行していないことが判明し、TDD の判定が検証されないままになっていたため設けられています。

ファイル4: quality/RUN_INTEGRATION_TESTS.md

テンプレートについては references/review_protocols.md を読んでください。

以下を必ず含めてください: 安全上の制約、事前チェック、具体的な合格基準を持つテストマトリクス、実行の UX セクション、構造化されたレポート形式。正常系、バリアント間の一貫性、出力の正しさ、コンポーネント境界を網羅してください。

ユースケースのトレーサビリティ（必須）。 テストマトリクスには、ユースケースのトレーサビリティ列を含める必要があります。各統合テストグループは、次のいずれかに該当しなければなりません。

1. ユースケースに対応付ける — 検証対象のユースケース（例: UC-03）を明記し、そのユースケースのユーザーにとっての成果をテストがどのように検証するかを説明してください。これらは主要な統合テストであり、ユースケースに記述されたエンドツーエンドの動作が実際に機能することを検証します。

2. インフラとしてラベル付けする — ユースケースに対応しないテスト（ビルド検証、レース検出、互換性チェック、既存テストスイートの回帰ガードなど）は、トレーサビリティ列で明示的に [Infrastructure] とラベル付けしてください。これらには価値がありますが、ユースケースのカバレッジには含まれません。

テストマトリクスを生成した後、REQUIREMENTS.md のすべてのユースケースに、少なくとも1つの統合テストが対応付けられているかを確認してください。対応付けられていないユースケースがあれば、ギャップとして指摘してください。ユースケースに対応付けた統合テストは、ユースケースに記述されたエンドツーエンドの動作を検証しなければなりません。同じコードパスに触れるだけの既存ユニットテストを実行するだけでは不十分です。例えば、ユースケースが「開発者が認証付きでリダイレクトに従い、シークレットが漏洩しないこと」と述べているなら、統合テストは、認証ヘッダー付きでドメインをまたぐリダイレクトを実行し、それらのヘッダーが除去されていることを検証すべきです。単に pytest -k auth を実行するだけでは不十分です。

UC ごとのグループ分割（必須）。 各統合テストグループは、最大 2 つのユースケースに対応しなければなりません。3 つ以上の UC に対応するグループは粗すぎます。テストが失敗したときに、どのユースケースが壊れたかを区別できないためです。単一のテストコマンド（例: mvn test、go test ./...）で複数のユースケースが実行される場合は、ターゲットを絞ったテストセレクタ（-Dtest=、-run、-k、--tests、-- test_name など）を使って別々のグループに分割し、各グループが 1〜2 個の UC を分離するようにしてください。すべての UC を区別なく 1 つのコマンドでまとめて実行するグループは明示的に禁止します。失敗が起きても診断上の価値がないためです。

セレクタがない場合のフォールバック。 プロジェクトのテストフレームワークが、分割に必要な粒度でテストを選択できない場合（例: タグやフィルターをサポートしない一体型のテストスイート）は、その制約を統合プロトコルに記録し、実行可能な最も狭いコマンドを使用してください。そのグループがカバーする UC と、これ以上分割できない理由を記録してください。単一コマンドのプロジェクトであっても、必ず groups[] 形式の JSON スキーマを使用する必要があります。そのコマンドを、実行されるすべての UC を含む use_cases リストを持つ1つのグループにまとめてください。コマンドを並べただけのフラットなリストは、groups[] 構造の代わりとして有効ではありません。 実行前のコマンド検証（必須）。 RUN_INTEGRATION_TESTS.md を確定する前に、各グループのテストコマンドで実際にテストが検出され、実行されることを確認してください。フレームワークのドライランまたは一覧表示モードを使って確認します。

• Python： pytest --collect-only -q <selector> — テストが少なくとも1件表示される必要があります
• Go： go test -list "." <package> — テスト名が少なくとも1件表示される必要があります
• Java/Kotlin： mvn -Dtest=<selector> test -pl <module> --batch-mode -DfailIfNoTests=true
• TypeScript (Vitest)： vitest list <file> --config <config> — テストが少なくとも1件表示される必要があります
• TypeScript (Jest)： jest --listTests <pattern> — ファイルが少なくとも1件表示される必要があります
• Rust： cargo test <selector> -- --list — テストが少なくとも1件表示される必要があります
• JavaScript (Mocha)： mocha --dry-run <file> — テストが少なくとも1件表示される必要があります

ドライランが「no tests found」、「No test files found」、またはテスト数がゼロで終了した場合は、グループを記録する前にセレクターを修正してください。よくある修正方法：--config または --root フラグを追加する、-t の名前パターンではなくファイルパスを使う、正しいパッケージに正規表現パターンを指定する。検出に失敗するコマンドを含むグループは記録しないでください。セレクターの不具合がコードの不具合として扱われ、covered_fail の結果が出てしまいます。

ドライランが「テストが見つからない」ではなく、ビルドエラー（コンパイル失敗、インポートエラー、依存関係の不足、テストセットアップ例外）で失敗した場合は、その失敗をグループの notes フィールドに "pre_flight_error": "environment" として記録し、セレクターは修正しないでください。実行前の環境エラーには、セレクターの変更ではなく環境のセットアップが必要です。

インフラストラクチャグループの定義。 単一の [Infrastructure] グループでは、UC マッピングなしでビルド検証、競合検出、静的解析、プラットフォーム互換性チェックを対象にできます。インフラストラクチャテストは、ユーザーが観察できる動作ではなく、ビルドツールチェーンとプラットフォームのサポートを検証します。インフラストラクチャグループ：

• ユースケースのカバレッジには含めません（UC カバレッジチェックでは無視されます）
• 検証内容を説明する1行の根拠を含める必要があります
• 分割を避けるために、幅広いユーザーワークフローのコマンドを付け替える目的で使用してはいけません。テストがユースケースに記述されたユーザー向けの動作を検証する場合、テストの構成にかかわらず、その UC にマッピングする必要があります

すべてのコマンドで相対パスを使用してください。 生成されるプロトコルには、すべてのコマンドを相対パスでプロジェクトルートから実行することを示す「Working Directory」セクションを先頭に含めてください。絶対パスに cd するコマンドは生成しないでください。プロトコルを別のマシンやディレクトリで実行すると動作しなくなります。./scripts/、./pipelines/、./quality/ などを使用してください。

Execution UX セクションを含めてください。 誰かから「統合テストを実行して」と指示された AI エージェントが、作業内容をどのように提示するかを把握できるようにする必要があります。プロトコルでは次の3つのフェーズを指定してください。（1）何も実行する前に、番号付きの表で計画を示す、（2）各テストの実行中に1行の進捗状況（✓/✗/⧗）を報告する、（3）合格数と失敗数、および推奨事項を記載したサマリー表を示す。テンプレートと例は references/review_protocols.md の「Execution UX」セクションを参照してください。これがないと、エージェントは生の出力をそのまま表示するか、何も報告しないかのどちらかになり、いずれも役に立ちません。

構造化出力（必須）。 プロトコルでは、Markdown レポートと併せて、機械可読な結果を出力するようエージェントに指示する必要があります。テスト実行には JUnit XML、QPB 固有のメタデータには サイドカー JSON を使用してください。

JUnit XML 出力： 各テストグループでは、フレームワーク標準の JUnit XML レポーターを使用して実行してください。

• Python：pytest --junitxml=quality/results/integration-group-N.xml
• Go：gotestsum --junitxml quality/results/integration-group-N.xml -- -run "TestPattern"
• Java/Kotlin：Surefire の XML レポートを quality/results/ にコピーする
• TypeScript：JEST_JUNIT_OUTPUT_DIR=quality/results/ を指定して jest --reporters=jest-junit を実行する
• Rust：cargo test 2>&1 | cargo2junit > quality/results/integration-group-N.xml（利用可能な場合） JUnit XML レポーターを利用できない場合は、XML をスキップし、サイドカー JSON に "junit_available": false と記載してください。

サイドカー JSON： 以下のテンプレートをそのままコピーし、値のみを入力して、quality/results/integration-results.json を生成してください。フィールドを新たに追加したり、キー名を変更したり、スキーマを再構成したりしないでください。groups 配列のないコマンドのフラットなリストは、プロジェクトがすべてのテストを単一のコマンドで実行する場合でも無効です。必ず 1 つのグループにまとめてください。

{
  "schema_version": "1.1",
  "skill_version": "<current skill version>",
  "date": "YYYY-MM-DD",
  "project": "<project name>",
  "recommendation": "SHIP",
  "groups": [
    {
      "group": 1,
      "name": "Core routing dispatch",
      "use_cases": ["UC-01", "UC-02"],
      "result": "pass",
      "tests_passed": 5,
      "tests_failed": 0,
      "junit_file": "integration-group-1.xml",
      "junit_available": true,
      "notes": ""
    }
  ],
  "summary": {
    "total_groups": 9,
    "passed": 8,
    "failed": 1,
    "skipped": 0
  },
  "uc_coverage": {
    "UC-01": "covered_pass",
    "UC-02": "covered_pass",
    "UC-03": "not_mapped"
  }
}

必須のトップレベルフィールド： schema_version、skill_version、date、project、recommendation、groups、summary、uc_coverage。出力にこれらのフィールドが 1 つでも欠けている場合、要件に適合しません。

無効な例（出力しないでください）：

• フラットな "results": [{"command": "go test ./...", "result": "pass"}] — グループ化されたスキーマではありません。
• "groups" の代わりに "commands_run" を使用したスキーマ — キー名が誤っています。
• "uc_coverage" がないスキーマ — REQUIREMENTS.md のすべてのユースケースを含める必要があります。
• "use_cases" の代わりに "use_case_traceability" を使用したスキーマ — フィールド名が誤っています。

有効な result の値："pass"、"fail"、"skipped"、"error"。有効な recommendation の値："SHIP"（すべてのグループが pass）、"FIX BEFORE MERGE"（ブロッキングではないグループに失敗がある）、"BLOCK"（クリティカルなグループに失敗がある）。uc_coverage セクションでは、REQUIREMENTS.md のすべてのユースケースを次のいずれかに対応付けます："covered_pass"（対応付けられたグループが少なくとも 1 つ成功）、"covered_fail"（グループは対応付けられているが、すべて失敗）、"not_mapped"（ユースケースに対応する統合テストグループがない）。"covered_fail" と "not_mapped" の違いは重要です。前者はテストが存在するもののコードが壊れていることを意味し、後者はテストが欠けていることを意味します。

ランナースクリプトと CI ツールは、Markdown レポートを grep するのではなく、結果をサイドカー JSON から読み取ってください。これにより、grep によるカウントで文章中の単語に一致して数値が誤るという類のバグを排除できます。

書き込み後の検証（必須）。 integration-results.json を書き込んだ後、ファイルを再度開いて次の点を確認してください：（1）必須のトップレベルフィールドがすべて存在すること、（2）groups[] の各エントリに group、name、use_cases、result、notes があること、（3）すべての result と recommendation の値が、上記の許可された列挙値のみを使用していること、（4）uc_coverage が REQUIREMENTS.md のすべてのユースケースに対応していること、（5）ドキュメント化されていない余分なルートキーがないこと。いずれかの確認に失敗した場合は、先に進む前にファイルを修正してください。

このプロトコルでは、実際の外部依存関係を使用してテストする必要があります。 プロジェクトが API、データベース、外部サービスと通信する場合、統合テストプロトコルでは、ローカルでの検証だけでなく、これらのサービスに対する実際のエンドツーエンド実行を行ってください。プロジェクトの実際の実行モードと外部依存関係に基づいてテストマトリックスを設計してください。探索中に API キー、プロバイダー抽象化、既存の統合テストスクリプトを探し、それらを活用してください。

一般的なチェックではなく、コードから品質ゲートを導き出してください。 探索中に検証ルール、スキーマの列挙値、生成ロジックを確認してください。それらをパイプラインごとの具体的なフィールドと許容値範囲を指定した品質チェックに落とし込んでください。「すべてのユニットが検証済み」だけでは不十分です。このプロトコルでは、ドメイン固有の正しさを確認する必要があります。

並列実行は説明するだけでなく、スクリプトで実装してください。 独立して実行できる処理（異なるプロバイダー）をグループ化して同時に実行してください。& と wait を含む実際の bash コマンドを記載してください。レート制限を避けるため、各プロバイダーにつき一度に実行するのは 1 つにしてください。

ユニット数はプロジェクトに合わせて調整してください。 chunk_size または同等の設定を確認してください。少なくとも 2 チャンクにまたがり、分布チェックを検証するのに十分な数のユニットを使用してください。統合テストでは通常 10～30 が目安です。

実行後の詳細な検証。 「プロセスが完了した」だけで終わらせないでください。すべての実行について、ログファイル、マニフェストの状態、出力データの存在、サンプルレコードの内容、既存の品質チェック用スクリプトを確認してください。 既存の検証ツールを探して使用してください。 出力品質を検証する既存のスクリプト（例：integration_checks.py、検証スクリプト、品質ゲート関数）を探してください。存在する場合は、プロトコルから呼び出してください。プロジェクトに TUI やダッシュボードがある場合は、実行後のチェックリストに TUI の検証コマンド（例：--dump フラグ）を含めてください。

品質ゲートを書く前に、フィールド参照表を作成してください。 これは、プロトコルの正確性にとって最も重要な手順です。AI モデルはスキーマを読んだ後でも、フィールド名を自信たっぷりに間違えて記述します。たとえば、document_id が doc_id に、sentiment_score が sentiment に、「float 0-1」が「int 0-100」になります。これを防ぐ方法は手順にあります。表の各行を書く直前に、各スキーマファイルを読み直してください。 会話の前のほうで読んだ内容に頼らないでください。何千トークンも経つと、フィールド名の記憶は曖昧になります。ファイルの内容から、フィールド名を一字一句そのまま転記してください。各スキーマのフィールドをすべて含めてください（スキーマにフィールドが8つある場合、表には8行必要です）。全手順と形式については、references/review_protocols.md の「The Field Reference Table」セクションを参照してください。この手順を省略しないでください。これは、プロトコルで最もよくある不正確さを防ぎます。

ファイル 5：quality/RUN_SPEC_AUDIT.md — 3者による監査

詳細なプロトコルについては、references/spec_audit.md を読んでください。

独立した3つのAIモデルで、仕様に照らしてコードを監査します。なぜ3つなのでしょうか。それぞれのモデルには異なる見落としがあります。実際、監査担当者が異なれば、発見する問題も異なります。相互に照合することで、どのモデルも単独では見つけられない問題を検出できます。

このプロトコルでは、ガードレール付きのコピー＆ペースト可能な監査プロンプト、プロジェクト固有の重点確認領域、優先度付けのプロセス（確信度に応じた指摘の統合）、修正の実行ルール（巨大なプロンプトではなく、サブシステムごとの小さなバッチ）を定義します。

重点確認領域の補助的な割り当て： 任意で、各監査モデルに補助的な重点領域を割り当ててもかまいません。たとえば、1つは入力検証、1つはリソースのライフサイクル、1つは並行性から確認を始めます。各モデルは引き続き、完全に独立した監査を実施します。重点領域は確認の優先度に影響を与えますが、対象範囲を制限するものではありません。モデルごとにバグの種類を分担し、重複のない担当領域を割り当てないでください。

少数意見の指摘に関するルール： 優先度付けの際、3人の監査担当者のうち1人だけが指摘した事項（少数意見の指摘）は、再調査が必要です。具体的なコードの位置を読み、既定で破棄するのではなく、「CONFIRMED」または「FALSE-POSITIVE」のどちらかを明示的に判断してください。少数意見の指摘には、他の2つのモデルが見落とした実際のバグが含まれる可能性が、比較的高くあります。

優先度付けの際に、証拠の基準をコードパスの分析より高くしてはいけません。 優先度付けの手順では、指摘を確認または却下します。実行時の証拠が出るまで判断を保留するものではありません。指摘に、振る舞いの違反を示すコードパスの追跡（関数呼び出し、欠落している分岐、誤った戻り値とファイル名・行番号の参照）が含まれている場合は、優先度付けでその指摘を確認してください。コードパスの追跡で裏付けられた指摘を、「候補」や「実行時の検証が必要」に格下げしないでください。TDD プロトコル（フェーズ5）では、確認の後に実行時の証拠を取得します。証拠基準の詳細については、BUGS.md セクションの「What counts as sufficient evidence to confirm a bug」を参照してください。

コードレビューと仕様監査で指摘が食い違う場合： コードレビューと仕様監査で同じ指摘に対する判断が異なっても、仕様監査の指摘が自動的に正しいとは限りません。検証プローブを実施し、該当するコードの位置を読み、どちらの判断が正確かを明らかにしてください。解決結果はバグトラッカーに記録してください。仕様監査のどの担当者も指摘しなかったコードレビューの BUG も、確認済みとして扱います。ただし、クローズする前に対象を絞ったプローブで検証してください。

検証プローブは、実行可能な証拠を生成しなければなりません。 優先度付けの手順で、検証プローブを使って指摘を確認または却下する場合、文章による推論だけでは不十分です。その判断を機械的に証明するテストアサーションを、プローブで生成する必要があります。

• 棄却する場合（指摘が誤検知である場合）：指摘が誤りであることを証明する、PASS するアサーションを記述してください。例：「関数 X に NULL チェックがない」という指摘を棄却する場合は、assert "if (ptr == NULL)" in source_of("X"), "X has null check at line NNN" と記述します。棄却を証明する PASS するアサーションを記述できない場合は、その指摘を棄却せず、確認済みとしてエスカレーションするか、手動レビューの対象にしてください。

• 確認する場合（指摘が実際のバグである場合）：バグの存在を証明する、FAIL するアサーション（失敗が想定されるアサーション）を記述してください。例：「switch に RING_RESET がない」という指摘を確認する場合は、assert "case VIRTIO_F_RING_RESET:" in source_of("vring_transport_features"), "RING_RESET should be in the switch but is not" と記述します。

• すべてのアサーションで、参照する証拠の正確な行番号を示す必要があります。「3527〜3528 行」ではなく、「3527 行：default:」のように、その行に実際に記載されている内容を示してください。行番号の引用がないアサーションは不十分です。

このルールがある理由： v1.3.16 の virtio テストでは、VIRTIO_F_RING_RESET が switch/case の許可リストにないという少数派の指摘が、トリアージに正しく届きました。トリアージは「検証プローブ」を実行し、3527〜3528 行には「VIRTIO_F_RING_RESET が明示的に保持されている」と主張しました。しかし、実際にはその行には default: 分岐が記載されていました。トリアージは、コードが要件を満たしていると幻覚していました。assert "case VIRTIO_F_RING_RESET:" in source の記述が必須であれば、アサーションは失敗し、幻覚が明らかになっていたはずです。棄却に実行可能な証拠を求めることで、幻覚による棄却は自滅します。コードに存在しないものについて、モデルは PASS するアサーションを記述できないからです。

トリアージの証拠はディスクに書き込む必要があります。 検証プローブのアサーションは、quality/mechanical/verify.sh に追記するか、専用の quality/spec_audits/triage_probes.sh に記述するなど、ディスク上のファイルに含めてください。トリアージレポートの本文で説明されていても、実行可能ファイルに書き込まれていないアサーションは、実行可能な証拠ではありません。ゲートはトリアージ出力にプローブのアサーションが存在するかをチェックします。実行可能ファイルに対応するアサーションがないのに「検証プローブで確認済み」と記載するトリアージレポートは、要件に準拠していません。これにより、実際には実行せず、プローブを実行したら何がわかるかをモデルが語るという失敗パターンを防ぎます。

File 6: AGENTS.md（オーケストレーターが生成。Phase 2 では作成しません）

v1.5.4 の契約: AGENTS.md は Phase 6 が成功した後に bin/run_playbook.py によって生成されます。Phase 2 中に作成するものではありません。 オーケストレーターの _safe_write_agents_md ヘルパーは、Phase 2 で作成した quality/ の成果物と Phase 6 のゲート判定結果を入力として、ファイルをターゲットのリポジトリルート（quality/AGENTS.md ではなく <target>/AGENTS.md）に書き出します。生成されるファイルは、最初の空でない行に `` センチネルを持ち、以降の実行で QPB が管理するコピーを検出できるようにしています。

Phase 2 の LLM がしてはいけないこと:

1. <target>/AGENTS.md を作成しないでください。 このファイルはオーケストレーターが管理します。Phase 2 から作成すると、オーケストレーターの冪等な再生成パスと衝突し、ソース不変条件によってエラーとして検出される可能性があります。
2. 既存の <target>/AGENTS.md を変更しないでください。 ターゲットのリポジトリルートにファイルが存在し、QPB センチネルがない場合、それは運用者が作成したファイルです。そのまま残してください（オーケストレーターは _safe_write_agents_md の "preserved" の結果に従い、警告付きで保持します）。QPB センチネルがある場合は、Phase 6 の後にオーケストレーターが再生成します。実行の途中で編集して手伝う必要はありません。
3. quality/AGENTS.md を作成しないでください。 これは契約に含まれておらず、AGENTS.md は quality/ の下ではなく、リポジトリルートに置かれます。

既存の AGENTS.md に「Quality Docs」セクションを追加したくなった場合は、そこで止まってください。その作業はオーケストレーターが、Phase 6 のゲートが検証する正規のパスから内容を取得して行います。Phase 2 の成果物は quality/ 配下のファイルだけです。

このバグ修正は、2026-04-30 に表面化したブートストラップテストの障害パターンを防ぎます。 Phase 2 の LLM がこのセクションにある v1.5.3 時代の「AGENTS.md が既に存在する場合は更新する」という指示を読み、プロジェクトのルートの AGENTS.md に Quality Docs セクションを追記しました。その結果、ソース不変条件が発動して実行が中断され、20 分間の Phase 2 の作業が破棄されました。

File 7: quality/RUN_TDD_TESTS.md（TDD 検証プロトコル）

このプロトコルは、コードレビューと仕様監査によってバグが確認され、修正パッチが生成された後に実行されます。確認された各バグについて赤・緑の TDD サイクルを実行します。つまり、修正前のコードではテストが失敗し、修正を適用するとテストが成功することを確認します。

なぜ別のプロトコルが必要なのですか？ コードレビューはバグを発見し、xfail マーカー付きの回帰テストを作成します。TDD プロトコルは、それらのテストが実際にバグを検出すること、そして修正が実際にバグを直すことを証明します。これは「バグを見つけてテストを書いた」よりも強い主張です。「パッチなしでは失敗し、パッチありでは成功するテストがある」ということを示すものです。上流にバグを報告する際にはこの違いが重要で、メンテナーはバグの説明よりも FAIL→PASS の実証を信頼します。

生成されるプロトコルには、次の内容を含める必要があります。

1. 仕様に基づくテスト要件。 quality/BUGS.md の各バグについて、プロトコルはエージェントに次の作業を指示します。

   • バグの仕様の根拠フィールドを読み、期待される動作を定義しているドキュメントの箇所を特定します。
   • 引用されたセクションで、収集済みのドキュメント（reference_docs/ またはプロジェクト自身のドキュメント）を読みます。
   • 仕様の用語を使ってテストのアサーションを書きます。変数名、定数、関数名、アサーションメッセージは、コードの内部的な命名ではなく、仕様の用語を反映しなければなりません。
   • 各テストには、次を引用するコメントブロックを含めます。要件 ID（REQUIREMENTS.md より）、バグ ID（BUGS.md より）、仕様の箇所（ドキュメント名、セクション、動作契約の 15 語以内の引用）。

2. 赤・緑の実行手順。 修正パッチがあるバグごとに、次の手順を実行します。

   • 赤（Red）: 修正前のソースに対して回帰テストを実行します。テストは失敗しなければなりません。成功してしまった場合、そのテストはバグを検出していません。仕様の根拠をもとに、どの動作をアサートすべきかを理解してテストを書き直してください。
   • 緑（Green）: 修正パッチ（git apply quality/patches/BUG-NNN-fix.patch）を適用し、同じテストを実行します。テストは成功しなければなりません。
   • 記録: 両方の結果をバグトラッカーに記録し、クローズのステータスを「TDD verified (FAIL→PASS)」とします。

3. フレームワークへの適応。 プロトコルはプロジェクトのテストフレームワークを検出し、慣用的なテストを生成する必要があります。

   • テスト基盤があるプロジェクト（pytest、JUnit、Go testing、Jest、cargo test など）：探索中に確認した既存のテスト規約に従い、プロジェクトで使用しているフレームワークでテストを作成します。
   • テスト基盤がないプロジェクト（Linux カーネル、組み込み C など）：sed で対象の関数を抽出し、最小限の型シムを使った自己完結型の C テストファイルを作成して、直接コンパイルして実行します。自己説明的になるよう、抽出コマンドをテストファイルのヘッダーコメントに含めます。

4. アップストリームへの報告形式。 TDD で検証済みのバグごとに、すぐに送信できる以下の内容を含むレポートブロックを生成します。

   • 違反した仕様のセクションを挙げた、1 文での説明
   • FAIL→PASS の出力（コピーして貼り付けられるターミナルセッション）
   • テストファイル（添付またはインライン）
   • 修正パッチ（添付またはインライン）

5. トレーサビリティ表。 プロトコルは、以下を対応付ける quality/TDD_TRACEABILITY.md ファイルを生成します。

   Bug ID	Requirement ID	Spec Doc	Spec Section	Behavioral Contract	Test File:Function	Red Result	Green Result

   すべての行を漏れなく記入する必要があります。仕様書の項目がないバグは仕様違反ではなくコードの不整合です。この点を表に記載し、それに応じてアップストリームへの報告文言を調整します。

6. 構造化出力（必須）。 プロトコルは、Markdown レポートと併せて機械可読な結果を生成する必要があります。テスト実行結果には JUnit XML を使用し、JUnit XML では表現できない QPB 固有のメタデータにはサイドカー JSON ファイルを使用します。

   JUnit XML 出力： red-green の各フェーズで、フレームワーク標準の JUnit XML 出力フラグを使ってテストを実行します。

   • Python：pytest --junitxml=quality/results/tdd-red-BUG-NNN.xml
   • Go：gotestsum --junitxml quality/results/tdd-red-BUG-NNN.xml -- -run TestRegression_BUG_NNN
   • Java/Kotlin：Maven Surefire レポートは target/surefire-reports/ に自動生成されます。関連する XML を quality/results/ にコピーします。
   • Rust：cargo test --test regression 2>&1 | cargo2junit > quality/results/tdd-red-BUG-NNN.xml（cargo2junit が利用可能な場合。そうでなければ、Rust の XML 出力は省略します）
   • TypeScript：JEST_JUNIT_OUTPUT_DIR=quality/results/ を指定して jest --reporters=default --reporters=jest-junit を実行します。

   フレームワークの JUnit XML レポーターが利用できない場合、または依存関係が不足していて使用できない場合は、その言語の XML 出力を省略し、サイドカー JSON に ("junit_available": false) と記載します。XML ツールが不足していても、TDD の実行を失敗させないでください。

   サイドカー JSON（スキーマの厳格な適用）： 以下のテンプレートをそのままコピーし、値だけを埋めて quality/results/tdd-results.json を生成します。フィールドの追加、キー名の変更、スキーマの再構成は行わないでください。このテンプレートがスキーマです。逸脱（余分なキー、欠落したキー、キー名の変更、ネスト構造の再構成）がある場合、出力は不適合になります。まずテンプレートをエディターにコピーしてから、値を埋めてください。JSON を記憶だけで書かないでください。

   {
     "schema_version": "1.1",
     "skill_version": "<current skill version>",
     "date": "YYYY-MM-DD",
     "project": "<project name>",
     "bugs": [
       {
         "id": "BUG-001",
         "requirement": "REQ-003",
         "red_phase": "fail",
         "green_phase": "pass",
         "verdict": "TDD verified",
         "regression_patch": "quality/patches/BUG-001-regression-test.patch",
         "fix_patch": "quality/patches/BUG-001-fix.patch",
         "fix_patch_present": true,
         "patch_gate_passed": true,
         "writeup_path": "quality/writeups/BUG-001.md",
         "junit_red": "tdd-red-BUG-001.xml",
         "junit_green": "tdd-green-BUG-001.xml",
         "junit_available": true,
         "notes": ""
       }
     ],
     "summary": {
       "total": 6,
       "verified": 4,
       "confirmed_open": 1,
       "red_failed": 1,
       "green_failed": 0
     }
   }
   

   必須のトップレベルフィールド： schema_version、skill_version、date、project、bugs、summary。バグごとに必須のフィールド： id、requirement、red_phase、green_phase、verdict、fix_patch_present、writeup_path。必須フィールドが 1 つでも欠けている場合、結果は不適合です。バグごとの任意フィールド（上のテンプレートに記載されていますが、ゲートチェックの対象外）：regression_patch、fix_patch、patch_gate_passed、junit_red、junit_green、junit_available、notes。データがある場合は含めてください。省略しても不利益はありません。 必須のサマリーサブキー: summary オブジェクトには、total、verified、confirmed_open、red_failed、green_failed の 5 つのキーを厳密に含める必要があります。5 つすべてが必須です。いずれかを省略すると（特に red_failed や green_failed）、サマリーは仕様に適合しなくなります。

   正規のパッチファイル名: リグレッションテストのパッチは BUG-NNN-regression-test.patch という名前にしてください。修正パッチは BUG-NNN-fix.patch という名前にしてください。ゲートスクリプトはこれらの正確なパターンを glob で検索します。BUG-001-regression.patch や BUG-001-test.patch のような独自の変形は集計されません。

   日付フィールド: テンプレートのプレースホルダー "YYYY-MM-DD" ではなく、このセッションの実際の日付（例: "2026-04-12"）を使用してください。ゲートは日付が実在する ISO 8601 の日付であることを検証し、プレースホルダー文字列や未来の日付は拒否します。

   無効な例（これらは出力しないでください）:

   • "runs": [{"phase": "red", "command": "...", "result": "4 xfailed"}] — これは "bugs" によるバグ単位のスキーマではなく、フラットな runs 配列です。
   • "generated"、"scope"、"status"、"testsRun" などの独自のルートキーを含むスキーマ — これらは標準のスキーマフィールドではありません。
   • "verdict": "skipped" — この値は非推奨です。代わりに "confirmed open" を使用し、red_phase: "fail" と green_phase: "skipped" を設定してください。
   • ルートに "schema_version" がない — tdd-results.json にはすべてこのフィールドを含める必要があります。

   有効な verdict の値: "TDD verified"（FAIL→PASS）、"red failed"（未パッチのコードでテストが成功した — テストがバグを検出していない）、"green failed"（修正後もテストが失敗する — 修正が不完全またはパッチが壊れている）、"confirmed open"（red フェーズが実行されバグが確認されたが、修正パッチは利用できない）、"deferred"（この環境では TDD を実行できない — 理由を notes に記載して使用）。"skipped" を verdict として使用しないでください — 確認されたすべてのバグには red フェーズの結果が必要です。verdict: "confirmed open" のバグは、red_phase: "fail"（red が実行され、バグが確認された）かつ green_phase: "skipped"（適用する修正がない）でなければなりません。有効な red_phase/green_phase の値: "fail"、"pass"、"error"（コンパイルまたは適用の失敗）、"skipped"（green のみ — red がスキップされることはありません）。patch_gate_passed フィールドは、パッチ検証ゲート（apply-check とコンパイル）が成功したかどうかを記録します。ゲートが失敗してパッチを修復した場合は false、修正パッチが存在しない場合は null です。writeup_path フィールドは、バグごとの解説ファイル（後述の「バグ解説の生成」を参照）を指します。そのバグについて解説が生成されなかった場合は null です。

   Runner スクリプトや CI ツールは、通過/失敗の件数を Markdown レポートから grep するのではなく、サイドカーの JSON から読み取るべきです。

   書き込み後の検証（必須）。 tdd-results.json を書き込んだ後、ファイルを開き直して次を確認してください: (1) 必須のトップレベルフィールドがすべて存在すること、(2) bugs[] の各エントリに必須のバグごとのフィールドがすべて存在すること、(3) verdict、red_phase、green_phase のすべての値が、上記で列挙した許可された列挙値のみを使用していること、(4) 文書化されていない余分なルートキーが存在しないこと。いずれかの確認に失敗した場合は、先へ進む前にファイルを修正してください。この手順は、最も一般的な失敗パターンを防ぎます。つまり、エージェントがテンプレートをコピーせず記憶からスキーマを言い換えてしまい、もっともらしいが仕様に適合しない出力を生成するケースです。

TDD 成果物の完了ゲート（必須）。 quality/BUGS.md に確認済みのバグが 1 つでも含まれる場合、quality/results/tdd-results.json は任意ではなく必須です。red フェーズの結果を持つバグが 1 つでもある場合（TDD で検証済みでも、確認済みで未修正でも）、quality/TDD_TRACEABILITY.md も必須です。バグが 0 件のリポジトリでは、両方のファイルを省略できます。バグを確認したのに tdd-results.json を生成しない実行は未完了であり、そのフェーズは完了できません。TDD を実行できないリポジトリ（環境がブロックされている、テスト基盤がない）の場合は、verdict: "deferred" と、理由を説明する notes フィールドを付けて tdd-results.json を生成してください（例: "environment_blocked: missing workspace Cargo.toml"、"no_test_infrastructure: kernel C code without userspace harness"）。deferred という verdict により、ファイルを黙って省略するのではなく、この欠落を可視化できます。 実行時の UX： 統合テストと同じ3段階のパターンを使用します。（1）検証するバグを番号付きの表で計画として示します。（2）各レッド・グリーンサイクルの実行中に、1行の進捗を報告します（FAIL ✓ → PASS ✓ または FAIL ✗ — test passes on unpatched code, rewriting）。（3）検証済み、失敗、書き換えの件数をまとめた表を示します。

7. バグ報告書の生成（確認済みのすべてのバグが対象）。 レッド→グリーンサイクルの成功後（verdict: "TDD verified"）、または修正なしで確認した後（verdict: "confirmed open"）、quality/writeups/BUG-NNN.md に単独で読める報告書を生成します。このファイルは、メンテナーへのメール送信、Jira チケットへの添付、リポジトリ外でのレビューを想定しています。読者がほかの品質関連成果物を参照しなくても内容を理解できるようにしてください。

   テンプレート（セクション1～4、6、7はすべての報告書で必須です。深掘りが必要と判断した場合は5を、関連するバグがある場合は8を追加します）：

   1. 概要 — 問題の内容、場所（ファイル:行）、実際に何が壊れるかを1段落で記述します。
   2. 仕様の参照先 — 違反している仕様の具体的なセクションと、入手できる場合は URL を記載します。コードが満たしていない動作上の要件を引用します（15語以内）。
   3. コード — バグのあるコードを、ファイル:行の引用とともに示します。「見た目がおかしい」だけではなく、仕様に照らしてなぜ誤りなのかを説明します。
   4. 確認できる結果 — 実際に何が壊れるかを記述します。「理論上は失敗する可能性がある」ではなく、どのような条件で、どのような症状が発生するのかを説明します。
   5. 深掘りの判断 (分析の拡張が必要な場合のみ記載) — セクション1～4を作成した後、結果がコードとテストだけから明らかかどうかを評価します。読者が「なぜ今まで誰も気づかなかったのか？」や「すべての設定で同じように影響するのか？」と合理的に疑問に思う場合は、分析を詳しく掘り下げます。バグのある関数の呼び出し元をたどり、どのコードパスでバグが表面化し、どのコードパスで覆い隠されるのかを示します。具体的な拡張の判断材料には、トランスポートや設定によって動作が異なること、一部の経路ではバグを覆い隠す機能フラグ、呼び出し元が間接的なディスパッチによって見えにくくなっていること、特定の実行時条件でのみ顕在化するネゴシエーションや初期化コードのバグなどがあります。結果がコードの直近の部分から明らかな場合（例：null 参照、オフバイワン）には、セクション1～4を簡潔にまとめ、このセクションは省略します。
   6. 修正 — 修正案をインラインの差分（統一 diff 形式）で示し、これが適切な修正である理由を簡潔に説明します。必ず具体的な差分を含めてください。個別の .patch ファイルがない、修正未確認のバグでも同様です。1行の変更（ケースラベルの追加、引数の修正など）であれば、その差分を記述します。より広範な変更が必要な場合は、根本的な欠陥を解消する最小限の差分を記述し、完全な修正に必要な追加変更を記載します。報告書にインラインの差分があることで、実際に対応できる内容になります。「修正パッチはありません」と記載した報告書は不完全であり、メンテナーの役に立ちません。形式の例：

      --- a/drivers/virtio/virtio_ring.c
      +++ b/drivers/virtio/virtio_ring.c
      @@ -3527,6 +3527,7 @@ void vring_transport_features(...)
       	case VIRTIO_F_ORDER_PLATFORM:
       	case VIRTIO_F_IN_ORDER:
      +	case VIRTIO_F_RING_RESET:
       	default:
      

   7. テスト — テストで証明できること、実行方法、未修正コードと修正済みコードで予想される出力を記載します。
   8. 関連する問題 (関連するバグがある場合のみ記載) — 同じ種類のほかのバグがあれば記載します。まだ確認できていないものも含めてください。関連する問題が特定されていない場合、このセクションは省略します。

   バージョンスタンプを含めること： ほかのすべての生成ファイルと同じ形式で、報告書ファイルの先頭に記載します。 確認済みのすべてのバグについて、必ず報告書を作成します。 確認済みのバグごとに、TDD で検証済みのものと確認済み未解決のものの両方について、quality/writeups/BUG-NNN.md に報告書を作成します。上記の番号付きセクションのテンプレート（セクション 1～8）を使用してください。確認済み未解決のバグについても、セクション 6 に修正案の差分を含め、同じテンプレートに従ってください（個別の .patch ファイルがなくても、差分は必ず必要です）。報告書作成の基準となるのはバグの確認であり、TDD の完了ではありません。確認済みのバグがあるのに報告書ディレクトリがない実行は未完了です。

   インライン差分はゲートで必須です。 quality_gate.py スクリプトは、すべての報告書に ```diff ブロックが含まれていることを確認します。インライン差分のない報告書があると、ゲートは FAIL になります。「パッチファイルを参照」と書かず、実際の差分をフェンス付きの ```diff コードブロック内に記載し、報告書本文に直接貼り付けてください。報告書だけを読む保守担当者がバグに対処できるようにするため、これが報告書の最も重要な要素です。

チェックポイント：成果物の生成後に PROGRESS.md を更新

quality/PROGRESS.md を再読します。以下を更新してください。

• Phase 2 を完了として、タイムスタンプを記録する
• 成果物一覧を更新し、生成した各成果物のステータスを「generated」にして、ファイルパスを記載する
• まだ記載されていない場合は、調査の概要メモを追加する

Phase 2 完了ゲート（必須）。 Phase 3 に進む前に、以下を確認してください。

1. すべての中核成果物が quality/ 配下に存在する（QUALITY.md、CONTRACTS.md、REQUIREMENTS.md、COVERAGE_MATRIX.md、COMPLETENESS_REPORT.md、test_functional.*、RUN_CODE_REVIEW.md、RUN_INTEGRATION_TESTS.md、RUN_SPEC_AUDIT.md、RUN_TDD_TESTS.md）。AGENTS.md はこの一覧に含まれません。Phase 2 ではなく Phase 6 の後にオーケストレーターが対象リポジトリのルートに書き込みます。
2. REQUIREMENTS.md に、抽象的な振る舞いの説明ではなく、実際のコード（ファイルパス、関数名、行番号）を参照する具体的な充足条件を持つ要件が記載されている。
3. ディスパッチ／列挙のコントラクトがある場合は、quality/mechanical/verify.sh が存在し、実行済みである。
4. PROGRESS.md で Phase 2 がタイムスタンプ付きで完了とされている。

Phase 3 を開始する前に、quality/PROGRESS.md と quality/REQUIREMENTS.md を再読してください。要件はコードレビューの対象一覧です。コードが充足条件を満たしていなければ、すべての要件がバグ候補です。

フェーズ終了メッセージ（必須。Phase 2 の完了後に出力し、その後停止してください）：

# Phase 2 Complete — Quality Artifacts Generated

I've generated the quality infrastructure for this project:
[List the key artifacts created: REQUIREMENTS.md with N requirements and N use cases,
QUALITY.md with N scenarios, functional tests, review protocols, etc.]

The requirements are now the target list for Phase 3's code review — every requirement
is a potential bug if the code doesn't satisfy it.

To continue to Phase 3 (Code review with regression tests), say:

    Run quality playbook phase 3.

Or say "keep going" to continue automatically.

このメッセージを出力したら停止してください。ユーザーから明示的に依頼されない限り、Phase 3 に進まないでください。

---

Phase 3：コードレビューと回帰テスト

v1.5.6 計測機能： 直ちに quality/run_state.jsonl に phase_start phase=3 を追記します。フェーズ終了時に相互検証（quality/RUN_CODE_REVIEW.md が存在すること、特定されたバグごとに報告書が1つあること）を行い、その後 phase_end phase=3 を追記します。

このフェーズで必ず参照する資料：

• quality/REQUIREMENTS.md — コードレビューの対象一覧
• references/review_protocols.md — 3 パスのプロトコルと回帰テストの規約

File 3 に記載されたコードレビュープロトコル（3 パスすべて）を実行します。問題点を特定したら、references/review_protocols.md のクローズ義務に従い、確認済みの BUG ごとに回帰テストを作成します。

PROGRESS.md を更新： 確認済みの BUG をすべて、累積 BUG トラッカーに追加します。各 BUG について、ソースを「Code Review」とし、ファイルと行の参照、説明、重大度、クローズ状況（回帰テストの関数名または免除理由）を記載します。Phase 3（コードレビュー＋回帰テスト）を完了として記録します。

フェーズ終了メッセージ（必須。Phase 3 の完了後に出力し、その後停止してください）：

# Phase 3 Complete — Code Review

The three-pass code review is done. [Summarize: N bugs confirmed, N regression test
patches generated, N fix patches generated. List the bug IDs and one-line summaries.]

To continue to Phase 4 (Spec audit — Council of Three), say:

    Run quality playbook phase 4.

Or say "keep going" to continue automatically.

このメッセージを出力したら停止してください。ユーザーから明示的に依頼されない限り、Phase 4 に進まないでください。

---

フェーズ 4：仕様の監査とトリアージ

v1.5.6 の計測： 今すぐ phase_start phase=4 を追加します。各パス A/B/C/D について、pass_started phase=4 pass=X と pass_ended phase=4 pass=X を追加します。フェーズ終了時に相互検証（quality/REQUIREMENTS.md が空でないこと、および quality/COVERAGE_MATRIX.md が存在すること）を行い、その後 phase_end phase=4 を追加します。

このフェーズで必須の参考資料：

• references/spec_audit.md — Three評議会プロトコル、トリアージプロセス、検証プローブ

File 5 の説明に従って、仕様監査プロトコルを実行します。トリアージレポートには、必ず ## Pre-audit docs validation セクションを含めてください（完全なテンプレートについては references/spec_audit.md を参照）。reference_docs/ が空の場合でも、このセクションは必須です。その場合は、監査担当者が代わりに使用したベースラインを記載してください。トリアージで行うすべての検証プローブは、上記の「検証プローブでは実行可能な証拠を提示する」ルールに従い、実行可能な証拠（行番号を引用したテストアサーション）を提示する必要があります。トリアージ後、確認済みの各指摘を分類してください。

列挙チェックに対する実効的な評議会ゲート。 実効的な評議会が 3/3 未満（利用可能なレポートを返した監査担当者が 3 人未満）で、実行にホワイトリスト／列挙／ディスパッチ関数のチェック、または引き継がれたシードチェックが含まれる場合、実行済みの機械的検証成果物なしに、これらのチェックについて「確認済みの不具合なし」と結論づけてはなりません。機械的検証を伴う評議会の不完全な構成は許容されます。コードの存在に関する主張を文章のみで検証する、不完全な評議会は許容されません。その場合は「NEEDS VERIFICATION」にエスカレーションし、終了前に機械的チェックを実行してください。

監査前のスポットチェックでは、ドキュメントの記述ではなくコードから抽出してください。 仕様監査のプロンプトに監査前検証用のスポットチェックの主張（例：「関数 X が行 Z で定数 Y を処理することを確認する」）が含まれている場合、トリアージでは、その主張が妥当に聞こえるかを確認するのではなく、引用された行にある実際のコードを抽出して各主張を検証する必要があります。コードの内容に関するスポットチェックの主張ごとに、監査前検証では引用された行に実際に何が含まれているかを報告してください。「3527 行目には default: が含まれています。主張されている case VIRTIO_F_RING_RESET: ではありません。」スポットチェックがコード自体ではなく、要件や収集したドキュメントから生成された場合は、確認する事実ではなく、検証すべき仮説として扱ってください。このルールは、v1.3.17 で見られたように、誤ったスポットチェックの主張（「3527～3528 行目に RING_RESET」）が実際の行を読まずに「正確」として受け入れられ、その後トリアージやすべての後続成果物に伝播する汚染の連鎖を防ぎます。

PROGRESS.md を更新： 仕様監査で確認されたすべての コードのバグ を、出典を「Spec Audit」として累積 BUG トラッカーに追加します。これは重要です。仕様監査で見つかったバグは、クローズ検証が参照する同じトラッカーに追加しないと、体系的に取り残されます。

レイヤー 2 — セマンティック引用チェック（v1.5.3 Council サブパス）

メインの仕様監査トリアージ後、各 Council メンバーは、すべての Tier 1/2 REQ の citation_excerpt に対して、REQ ごとの判定を行います。これは幻覚ゲートのレイヤー 2です。レイヤー 1 は機械的なバイト単位の一致チェックです。bin/citation_verifier は取り込み時に bin/reference_docs_ingest から呼び出され、ゲート実行時に quality_gate.py から再度呼び出されます。LLM がこれを直接シェルから実行することはありません。レイヤー 2 はセマンティックなチェックです。レビュー担当者は、抜粋が記載どおりの要件を実際に裏付けているか、あるいは要件が抜粋の記述を超えているかを判断します。

プロトコル。

1. Council メンバーごとに 1 つのプロンプトを使用し、すべての Tier 1/2 REQ をまとめて渡します。 REQ ごとに 1 つずつプロンプトを作る方法は避けます（3×N 個のプロンプトは多すぎます）。また、散文形式の回答も避けます（パターンマッチングのリスクがあります）。レビュー担当者には (req_id, citation_excerpt, REQ description) のタプルの全リストを渡し、REQ ごとに構造化された JSON レスポンスを返してもらいます。

2. 構造化レスポンスのスキーマ（schemas.md §9.2）。 レビュー担当者は各 REQ について、{"req_id": "REQ-NNN", "reviewer": "<stable string>", "verdict": "supports" | "overreaches" | "unclear", "notes": "<reasoning>"} を記録します。有効な verdict 値は schemas.md §3.5 で列挙されています。

3. バッチ処理のしきい値。 実行時に Tier 1/2 REQ が 15 件を超える場合は、Council メンバーごとに、1 プロンプトあたり最大 15 件の REQ に分割します。同じレビュー担当者が各バッチを順番に確認します。各バッチのレスポンス項目は、同じ reviewer 文字列の下で 1 つの reviews[] 配列に連結します。

4. レビュー担当者識別子の一貫性。 "claude-opus-4.7"、"gpt-5.4"、"gemini-2.5-pro" のような固定文字列を使用します。schemas.md の不変条件 #17 にある多数決の計算では、このフィールドでグループ化します。誤字があると、気付かないまま 4 人目のレビュー担当者として扱われ、2-of-3 の多数決チェックが機能しなくなります。

5. 出力。 §1.6 のマニフェストラッパーを使って、すべての Council メンバーのレスポンスを quality/citation_semantic_check.json に連結します。ただし、レコード配列の名前は records ではなく reviews です（schemas.md §9.1）。実行ごとに 1 ファイルを作成し、監査パスのたびに再生成します。

多数決ルール（ゲートで適用）。 各 Tier 1/2 REQ について、ゲートは req_id ごとにレビューをグループ化し、3 人中 2 人以上のレビュー担当者が verdict == "overreaches" を記録している場合、実行を失敗させます。1 人だけの overreaches または unclear 判定は警告として表示されますが、ゲートは失敗しません。レビュー担当者のエントリーが 3 件未満の REQ（レビュー担当者が不足している場合、バッチがスキップされた場合）は、証拠が不十分なため、ゲートは失敗として扱います。

Spec Gap 実行では何もしません。 実行時に Tier 1/2 REQ が 0 件でも、空の reviews 配列を含む citation_semantic_check.json を書き込みます。このチェックの評価対象がない場合でも、ファイルの存在は成果物の契約の一部です。

仕様監査後のリグレッションテスト

仕様監査のトリアージ後、PROGRESS.md の累積 BUG トラッカーを確認します。リグレッションテストがまだない仕様監査の BUG には、ここでテストを追加してください。仕様監査で確認されたコードのバグに対するリグレッションテストは、コードレビューのリグレッションテストと同じ規約（失敗予測マーカー、テストと検出事項の対応、実行可能なソースファイル）に従って作成します。

このステップが必要な理由： コードレビューで見つかったバグには、レビュー直後にテストが作成されるため、すぐにリグレッションテストが追加されます。仕様監査はテスト作成後に実施されるため、そこで確認されたバグは孤立し、トリアージレポートには記載されてもテストが作成されません。このステップでその抜けを埋めます。

個々の監査担当者の成果物（必須）。 仕様監査では、quality/spec_audits/ に、ファイル名に auditor を含む個別の監査担当者レポートを作成する必要があります（標準形式：YYYY-MM-DD-auditor-N.md、例：2026-04-12-auditor-1.md。auditor_<model>_<date>.md も使用できます）。ゲートは *auditor* を対象に検索するため、条件を満たす名前であれば一致します。トリアージの統合レポートだけでなく、監査担当者ごとに 1 ファイル作成してください。各監査担当者のレポートには、トリアージで照合する前に、その担当者が個別に発見した内容を記録します。個別の監査成果物がなく、トリアージファイルしか存在しない場合、監査は未完了です。事前調整段階の発見事項が記録されていないため、トリアージでの検証ができません。単一のトリアージファイルでは発見と照合が混同され、ある指摘事項が独立して確認されたのか、単一の情報源から統合されたのかを判別できないため、この要件が設けられています。

Phase 4 の完了ゲート。 quality/spec_audits/YYYY-MM-DD-triage.md にトリアージファイルが存在し、かつ個別の監査担当者レポートも存在するまで、Phase 4 は完了ではありません。監査担当者レポートだけがあり、トリアージの統合レポートがない場合は、PROGRESS.md で Phase 4 を「partial — triage pending」とし、次に進む前にトリアージを完了します。トリアージだけがあり、個別のレポートがない場合は、Phase 4 を「partial — auditor artifacts missing」とし、レポートを再生成します。トリアージファイルと監査担当者レポートの両方が存在することを確認するまで、PROGRESS.md のチェックボックスをオンにしてはいけません。

BUG トラッカーの項目を更新し、リグレッションテストへの参照を追加します。Phase 4（仕様監査＋トリアージ）を完了としてマークします。

フェーズ終了時のメッセージ（必須 — Phase 4 の完了後にこれを出力し、その後停止してください）：

# Phase 4 Complete — Spec Audit

The Council of Three spec audit is done. [Summarize: N auditors ran, N net-new bugs
confirmed from triage, total bugs now at N. List any new bug IDs and summaries.]

To continue to Phase 5 (Reconciliation — TDD verification, writeups, closure), say:

    Run quality playbook phase 5.

Or say "keep going" to continue automatically.

このメッセージを出力した後、停止してください。ユーザーから明示的な依頼がない限り、Phase 5 に進んではいけません。

---

Phase 5：レビュー後の照合と完了確認

v1.5.6 の計測： 今すぐ phase_start phase=5 を追記します。各ゲート確認について、gate_check gate_name=X verdict=pass|fail|warn|skip を追記します。フェーズ終了時に相互検証を行い（quality/results/quality-gate.log が空でないこと）、その後 phase_end phase=5 を追記します。

ソース編集のガードレール（必須）。 Phase 5 では、パッチの成果物を quality/patches/<BUG-NNN>-fix.patch および quality/patches/<BUG-NNN>-regression-test.patch として作成し、修正案を提示します。Phase 5 で quality/ の外にあるソースファイルへこれらのパッチを適用してはいけません。対象のソースツリーを変更するセルフ監査実行は、正当な Phase 5 の成果物ではなく、不具合です。パッチを適用するタイミングは、別途監督下で実施するステップとしてオペレーターが決定します。実行終了時にプレイブックが bin.run_state_lib.validate_no_source_edits(target_dir) を呼び出します。このヘルパーが quality/ 以外の変更済みパスを報告した場合は、違反内容を記載した error recoverable:false イベントを追記し、run_end status=aborted で実行を終了します。このルールは、2026-05-02 の Codex ブートストラップ実行で Phase 5 が逸脱し、停止される前に quality/ 外のソースファイル 5 件を編集したことを受け、v1.5.6 で再確認されました。

このフェーズで必要な参照資料：

• quality/PROGRESS.md — 累積 BUG トラッカー（正式な指摘事項一覧）
• references/challenge_gate.md — 誤検知を検出するための2ラウンドのチャレンジプロトコル
• references/requirements_pipeline.md — レビュー後の調整プロセス
• references/review_protocols.md — 判定覆し後の回帰テストの整理
• references/spec_audit.md — 競合に関する検証プローブのプロトコル

Phase 5 の開始ゲート（必須 — HARD STOP）。 作業を進める前に、Phase 4 の成果物がすべて存在することを確認してください。

1. quality/spec_audits/ ディレクトリが存在し、少なくとも1つの *triage* ファイル（トリアージの統合結果）が含まれている
2. quality/spec_audits/ に少なくとも1つの *auditor* ファイル（監査担当者ごとのレポート）が含まれている
3. quality/PROGRESS.md が存在し、Phase 4 の行に [x] が付いている

いずれかが欠けている場合は、作業を停止して Phase 4 に戻ってください。仕様監査の成果物が存在することを確認するまで、調整に進まないでください。トリアージデータなしで調整すると、完了レポートが不完全になります。

quality/PROGRESS.md を読み直してください。特に、累積 BUG トラッカーを確認します。これは、コードレビューと仕様監査の両方で見つかったすべての指摘事項の正式な一覧です。

チャレンジゲート（調整前に必須）。 完了検証を実行する前に、自動トリガーパターンに該当する確定済みのバグすべてにチャレンジゲートを適用してください。完全なプロトコルについては、references/challenge_gate.md を読んでください。概要は次のとおりです。

1. BUG トラッカーを確認し、自動トリガーパターンのいずれかに該当するバグを探します（セキュリティクラスの指摘、指摘箇所に設計判断のコメントがあるコード、仕様上の根拠がない指摘、同じ問題を扱う類似コードパスで処理が異なる指摘、機能不足に関する指摘）。
2. トリガーされたバグごとに、参照資料に記載された方法で、新しいサブエージェントを使って2ラウンドのチャレンジを実施します。
3. 判定結果を quality/challenge/BUG-NNN-challenge.md に記録します。
4. 判定を適用します。CONFIRMED のバグは通常どおり処理します。DOWNGRADED のバグは重大度を調整します。REJECTED のバグは BUG トラッカーから削除し、チャレンジの理由とともに BUGS.md の「レビュー済み・却下」付録に移します。

全体を通して常識に基づいて判断してください。 チャレンジゲートの主な目的は、パターンマッチングによって判断が覆された指摘を見つけることです。上流のメンテナーに報告したら愚かに見えるようなバグ――自己説明的なプレースホルダーを重大な脆弱性とする指摘、文書化された設計判断を欠陥とする指摘、意図的な機能不足をセキュリティ上の穴とする指摘――は、チャレンジを通過させてはいけません。常識に基づく判断は、多くの要素のうちの一つではありません。レビュー全体の枠組みとなるものです。

このゲートが必要な理由： v1.4.6 の edgequake ベンチマークでは、コードレビューで42件のバグが確認され、そのうち7件が CRITICAL と評価されました。手動レビュー後、最も重大な指摘（BUG-001、source_ids の上書き）は CRITICAL ではなく HIGH でした。「CRITICAL」とされたテナント分離のバグ6件は、明示的な WHY-OODA81 注釈が付いた、文書化済みの機能不足でした。「CRITICAL」とされた JWT の指摘（BUG-041）は、文字列「change-me-in-production」をそのまま含む、開発用の自己説明的なプレースホルダーでした。モデルは、欠陥とは何かについて常識に基づいて判断するのではなく、バグを見つけて擁護することに意識が向いていたため、何度も異議を受けてもこれらの指摘を擁護しました。チャレンジゲートを設けることで、指摘を最終確定する前に、この常識に基づくレビューを必ず行います。

1. レビュー後の照合作業を実行します。references/requirements_pipeline.md の説明に従ってください。COMPLETENESS_REPORT.md を更新してください。
2. クローズ検証を実行します。BUG トラッカーの各行について、回帰テストへの参照または明示的な免除のいずれかがあることを確認してください。どちらもない BUG がある場合は、今すぐテストまたは免除を記載してください。
3. トリアージと BUGS.md の同期ゲート（必須）。 トリアージレポート（quality/spec_audits/*-triage.md）を再読してください。コードのバグであると確認された指摘事項はすべて、quality/BUGS.md に記載されていることを確認してください。BUGS.md が存在しない場合は、今すぐ作成してください。BUGS.md が存在するものの、トリアージで確認されたバグが記載されていない場合は、追記してください。コードのバグが確認されたトリアージレポートに対応する BUGS.md の項目がない場合、要件不適合です。同期が完了するまでフェーズを完了としてマークできません。このゲートは、v1.3.21 のベンチマークで javalin のトリアージが 2 件のバグを確認したにもかかわらず、BUGS.md が作成されなかったことを受けて設けられました。
4. 仕様監査による判定変更後の整理： 仕様監査で、コードレビュー上の BUG が設計上の選択または誤検出に再分類された場合は、references/review_protocols.md に従って、対応する回帰テストを削除するか、別の場所に移してください。
5. コードレビューと仕様監査の不一致を解決： コードレビューと仕様監査が同じ指摘事項について異なる判定（片方は BUG、もう片方は設計上の選択）をしている場合は、references/spec_audit.md に従って検証プローブを実行し、BUG トラッカーに解決結果を記録してください。

TDD サイドカーとログの整合性チェック（必須）。 tdd-results.json の各バグ項目について、対応するログファイルが存在し、内容が一致していることを確認してください。tdd-results.json に verdict: "TDD verified" のバグがある場合、quality/results/BUG-NNN.red.log が存在し、その1行目が RED であること、さらに quality/results/BUG-NNN.green.log が存在することを確認してください。サイドカーが「TDD verified」としていても red フェーズのログが存在しない場合、その判定には根拠がありません。テストを実行してログを作成するか、判定を "confirmed open" に引き下げてください。このチェックは、v1.3.46 のベンチマークで、エージェントがテストを一度も実行せず、説明上の推論だけで JSON に「TDD verified」と記載していたことを受けて設けられました。

説明上の成果物より実行済みの証拠を優先（矛盾ゲート）。 ターミナルゲートを実行する前に、実行済みの証拠と文章による成果物の間に矛盾がないか確認してください。実行済みの証拠には、機械的検証の成果物（quality/mechanical/*）、検証結果のレシートファイル（quality/results/mechanical-verify.log、quality/results/mechanical-verify.exit）、回帰テストの結果（xfail の結果を含む test_regression.*）、TDD の red フェーズのログファイル（quality/results/BUG-NNN.red.log）、およびパイプライン中に保存されたシェルコマンドの出力が含まれます。文章による成果物には、REQUIREMENTS.md、CONTRACTS.md、コードレビュー、仕様監査のトリアージ、BUGS.md が含まれます。実行済みの成果物が、定数が存在しないこと（機械的チェック）、テストが失敗すること（回帰テスト）、またはバグが確認されたこと（TDD の追跡可能性）を示しているのに、文章による成果物が定数は存在する、バグは修正済み、またはコードは要件に適合していると主張している場合は、実行結果を優先してください。先に進む前に、矛盾する文章による成果物を再確認して修正してください。具体的には、mechanical-verify.exit にゼロ以外の値が含まれる場合、他の成果物の記述にかかわらず、PROGRESS.md に「機械的検証：合格」と記載してはならず、ターミナルゲートも合格してはなりません。v1.3.18 では、トリアージが RING_RESET は保持されていると主張し（spec_audits/triage.md）、BUGS.md が「作業ツリーで修正済み」としていた一方、TDD の追跡結果では、現在のソースに対して assert "case VIRTIO_F_RING_RESET:" in func が失敗していました。この3つがすべて真であることはあり得ません。実行による失敗が確かな事実です。このゲートがあれば、その矛盾を検出できていました。 バージョン表記の整合性チェック（必須）。 SKILL.md のメタデータから version: フィールドを読み取ります（参照ファイルの解決順序を使用）。次に、生成されたすべての成果物を確認します。PROGRESS.md の Skill version: フィールド、すべての > Generated by 帰属行、すべてのコードファイルのヘッダー表記、すべてのサイドカー JSON の skill_version フィールドです。すべてのバージョン表記が SKILL.md のメタデータと完全に一致している必要があります。1 つでも不一致があれば、ベンチマークは失敗です。先へ進む前に表記を修正してください。このチェックが設けられたのは、v1.3.21 のベンチマークで、PROGRESS.md のテンプレートにバージョン番号がハードコードされていたため、9 件中 5 件のリポジトリで古いスキルバージョン（v1.3.16 または v1.3.20）の表記が使われていたためです。

機械的なディレクトリ適合性チェック。 quality/mechanical/ が存在する場合、最低限 verify.sh ファイルを含める必要があります。空の quality/mechanical/ ディレクトリは不適合です。これは、そのステップを試みたものの放棄したことを意味します。このプロジェクトの対象範囲にディスパッチ関数の契約が存在しない場合は、mechanical/ ディレクトリを作成しないでください。代わりに、PROGRESS.md に次のように記録します。Mechanical verification: NOT APPLICABLE — no dispatch/registry/enumeration contracts in scope. ディスパッチ契約が存在する場合、verify.sh には quality/mechanical/ 内の保存済み抽出ファイルごとに検証ブロックを 1 つ含める必要があります（1 つだけでは不十分です）。複数の成果物があるのに 1 つしか検証しない verify.sh は不完全です。

検証レシートのゲート（ターミナルゲートの前に必須）。 quality/mechanical/ が存在する場合、ターミナルゲートを実行する前に、次のレシートファイルも存在している必要があります。

• quality/results/mechanical-verify.log — bash quality/mechanical/verify.sh の標準出力／標準エラー出力の全内容
• quality/results/mechanical-verify.exit — 終了コードを記載した 1 行（例：0）

いずれかのファイルが存在しない場合は、今すぐ bash quality/mechanical/verify.sh > quality/results/mechanical-verify.log 2>&1; echo $? > quality/results/mechanical-verify.exit を実行してください。終了コードが 0 でない場合、ターミナルゲートは失敗です。機械的な不一致を解消するまで先へ進まないでください（verify.sh やレシートを編集するのではなく、抽出内容を修正してください）。mechanical-verify.exit に 0 が記録されていない限り、PROGRESS.md に「Mechanical verification: passed」と記載してはいけません。このゲートが設けられたのは、v1.3.23 で verify.sh が実際には終了コード 1 を返していたにもかかわらず、PROGRESS.md にすべての検証が成功したと記載されていたためです。レシートファイルにより、この記載を監査できます。

TDD ログ完了ゲート（ターミナルゲートの前に必須）。 ターミナルゲートに進む前に、quality/BUGS.md から確認済みのすべてのバグ ID を列挙し、次の条件を確認してください。

1. 確認済みのすべてのバグについて、quality/results/BUG-NNN.red.log が存在すること。
2. そのバグについて quality/patches/BUG-NNN-fix.patch が存在する場合、quality/results/BUG-NNN.green.log も存在すること。
3. 各ログファイルの 1 行目が RED、GREEN、NOT_RUN、ERROR のいずれかであること。 いずれかの確認に失敗した場合は中止し、TDD 実行強制セクションに記載された言語対応のテスト実行コマンドを使って、今すぐ不足しているログを生成してください。TDD ログが不足したままターミナルゲートに進んではいけません。tdd-results.json で「TDD verified」と判定されたバグに対応する red フェーズのログがない場合、それは矛盾です。

ターミナルゲート（Phase 5 の完了をマークする前に必須）。

前提条件の確認： ターミナルゲートを実行できるのは、Phase 3（コードレビュー）と Phase 4（仕様監査）が両方完了しているか、PROGRESS.md で理由を明記してスキップ済みとされている場合のみです。バグが 0 件という結果が有効なのは、コードレビューと仕様監査の成果物が存在する場合（つまり、quality/code_reviews/ と quality/spec_audits/ ディレクトリにレポートファイルがある場合）に限られます。これらの成果物がなく、各フェーズも明示的にスキップされていない場合、ターミナルゲートは失敗です。Phase 5 を完了としてマークしないでください。 BUGS.md は常に必須です。 実行が完了するたびに、バグが見つかったかどうかにかかわらず、quality/BUGS.md を作成する必要があります。コードレビューと仕様監査でソースコードのバグがゼロであることが確認された場合は、## Summary に「確認済みのソースコードのバグは見つかりませんでした」と記載し、評価して除外した候補の数を列挙して BUGS.md を作成してください（例：「コードレビューでは N 件の候補を評価し、仕様監査では M 件の候補を評価しました。すべて設計上の選択、テストのみの問題、または誤検出として再分類されました」）。これにより、ファイルが存在しないという曖昧な状態ではなく、問題がないことを明確に示せます。BUGS.md がないまま実行を完了することは、要件に適合しません。

BUGS.md の見出し形式。 確認済みのバグにはそれぞれ、見出しレベル ### BUG-NNN を使用する必要があります（例：### BUG-001 または ### BUG-H1）。数値 ID（BUG-001）と、深刻度を表す接頭辞付き ID（BUG-H1、BUG-M3、BUG-L6）の両方が有効です。これが正式な見出し形式です。## BUG-001、**BUG-001**、箇条書きは使用しないでください。下流ツールはバグの件数を数えるために ### BUG-NNN の見出しを検索し、tdd-results.json の id フィールドもこれと一致させます。見出しレベルに一貫性がないと、機械可読な件数と文書の内容が食い違います。

quality/PROGRESS.md を読み直してください。BUG トラッカーの項目数を数えてください。そのうえで、次の作業を行ってください。

1. 次の文をユーザーに表示します（これは必須であり、省略できません）。

   「BUG トラッカーには N 件の項目があります。N 件には回帰テストがあり、N 件には免除があり、N 件は未解決です。コードレビューで M 件のバグが確認されました。仕様監査で K 件のコードバグ（うち L 件は新規）が確認されました。想定合計：M + L。」

2. 同じ文を PROGRESS.md の BUG トラッカー表の直後に、新しい ## Terminal Gate Verification セクションを作成して記載します。これにより、セッションログを読まなくてもレビュー担当者が確認できるよう、このゲートの記録が成果物に残ります。

トラッカーの項目数が M + L と一致しない場合は、作業を中断して整合させてください。BUG がトラッカーから漏れています。件数が一致するまで、Phase 5 を完了済みとしてマークしないでください。このゲートを設けたのは、v1.3.5 のブートストラップで、エージェントが仕様監査後にトラッカーを更新しないことが多く、確認済みバグの 30～50% がトラッカーから漏れていたためです。

回帰テスト関数名の検証： 回帰テストを参照している BUG トラッカーの各項目について、回帰テストファイル内でテスト関数名を検索し、その関数が存在することを確認してください。実際にはテストを作成していなくても、エージェントがトラッカーにテスト名を記載することがあります。参照されているテスト関数が存在しない場合は、ゲートを通過する前に作成してください。

3. PROGRESS.md の With docs メタデータフィールドが実際の状態と一致していることを確認します。reference_docs/ が存在し、ファイルを含んでいる場合は yes と記載し、それ以外の場合は no と記載します。誤っている場合は修正してください。

成果物のファイル存在ゲート（Phase 5 の完了をマークする前に必須）。 Phase 5 の完了チェックボックスを記入する前に、必須の成果物がすべて PROGRESS.md に記載されているだけでなく、ディスク上にファイルとして存在することを確認してください。次のチェックを実行してください（ls または同等のコマンドを使用します）。

• quality/BUGS.md が存在すること（ベンチマーク 34 により、完了したすべての実行で必須）
• quality/REQUIREMENTS.md が存在すること
• quality/QUALITY.md が存在すること
• quality/PROGRESS.md が存在すること（当然です。ここに書き込んでいます）
• quality/COVERAGE_MATRIX.md が存在すること
• quality/COMPLETENESS_REPORT.md が存在すること
• quality/formal_docs_manifest.json が存在すること（v1.5.3 — Phase 1 で bin/reference_docs_ingest.py が作成します。正式なドキュメントがない場合は、空の records[] も有効です）
• quality/requirements_manifest.json が存在すること（v1.5.3 — 正式な REQ レコード。REQUIREMENTS.md に出力されます）
• quality/use_cases_manifest.json が存在すること（v1.5.3 — 正式な UC レコード。USE_CASES.md／REQUIREMENTS.md の説明に出力されます）
• quality/citation_semantic_check.json が存在すること（v1.5.3 — Phase 4 の Layer-2 出力。Spec Gap 実行では空の reviews[] も有効です）
• Phase 3 を実行した場合：quality/code_reviews/ に .md ファイルが少なくとも 1 つ含まれていること
• Phase 4 を実行した場合：quality/spec_audits/ にトリアージファイルと個別の監査担当者ファイルが含まれていること
• Phase 0 または 0b を実行した場合：quality/SEED_CHECKS.md が単独ファイルとして存在すること（PROGRESS.md にインラインで記載しない）
• 確認済みのバグが存在する場合：quality/bugs_manifest.json が存在すること（v1.5.3 — schemas.md §8 に準拠した正式な BUG レコード）
• 確認済みのバグが存在する場合：quality/results/tdd-results.json が存在すること
• 確認済みのバグが存在する場合：quality/BUGS.md に記載された確認済みの各バグ ID について、quality/results/BUG-NNN.red.log が存在すること
• 修正パッチを伴う確認済みのバグが存在する場合：quality/patches/BUG-NNN-fix.patch がある各バグについて、quality/results/BUG-NNN.green.log が存在すること

不足しているファイルがあれば、今すぐ作成してください。成果物が不足した状態で Phase 5 を完了としないでください。PROGRESS.md に記載されたターミナルゲート検証は、参照先のファイルがディスク上に存在しなければ意味がありません。このゲートが設けられたのは、v1.3.24 のベンチマークで express がすべてのフェーズを完了し、PROGRESS.md にターミナルゲートのセクションを記載したにもかかわらず、BUGS.md、SEED_CHECKS.md、コードレビュー／仕様監査ファイルがディスクに書き込まれていなかったためです。

サイドカー JSON の書き込み後検証（必須）。 quality/results/tdd-results.json および／または quality/results/integration-results.json を書き込んだ後、各ファイルをすぐに再度開き、必須キーがすべて含まれていることを確認してください。tdd-results.json の必須ルートキーは、schema_version、skill_version、date、project、bugs、summary です。bugs の各エントリには、id、requirement、red_phase、green_phase、verdict、fix_patch_present、writeup_path が必要です。summary オブジェクトには、verified、red_failed、green_failed に加えて confirmed_open が必要です。integration-results.json の必須ルートキーは、schema_version、skill_version、date、project、recommendation、groups、summary、uc_coverage です。両ファイルとも、schema_version: "1.1" でなければなりません。キーが不足している場合は、今すぐ追加してください。形式に準拠しない JSON ファイルをディスク上に残さないでください。この検証が設けられたのは、v1.3.25 のベンチマークで、8 件中 6 件のリポジトリのサイドカー JSON が仕様に準拠していなかったためです。httpx は別のスキーマを独自に作成し、serde は旧形式を使用し、javalin は summary とバグごとのフィールドを省略し、ほかのリポジトリは無効な列挙値を使用していました。 スクリプト検証による完了ゲート（必須、Phase 5 完了のマークを付ける直前の最終ステップ）。 参照ファイルと同じフォールバック方式を使って quality_gate.py を検索します。次の6つの標準インストールレイアウトを順番に確認し、最初に見つかったものを使用します：quality_gate.py、.claude/skills/quality-playbook/quality_gate.py、.github/skills/quality_gate.py、.cursor/skills/quality-playbook/quality_gate.py、.continue/skills/quality-playbook/quality_gate.py、.github/skills/quality-playbook/quality_gate.py。プロジェクトのルートディレクトリから実行してください。このスクリプトでは、ファイルの存在、BUGS.md の見出し形式、サイドカー JSON の必須キーとバグごとのフィールド名（id、requirement、red_phase、green_phase、verdict、fix_patch_present、writeup_path）、列挙値、サマリーの整合性、ユースケース識別子、最終ゲートのセクション、機械的検証の証跡、バージョンスタンプ、報告書の完全性、確認済みのすべてのバグに対する回帰テストパッチの存在、および各報告書内の修正差分（すべての quality/writeups/BUG-NNN.md に ```diff ブロックが含まれていること）が機械的に検証されます。スクリプトが FAIL を報告した場合は、先に進む前に失敗したチェックをすべて修正してください。よくある FAIL は次のとおりです：（1）quality/patches/BUG-NNN-regression-test.patch ファイルがない、（2）bug_id のような標準外の JSON フィールド名が使われている（正しくは id）、（3）TDD サマリーに confirmed_open がない、（4）報告書に修正差分がない（セクション6には、「パッチファイルを参照」と記載するだけではなく、具体的な差分を含める必要があります）。quality_gate.py が終了コード0で終了するまで、Phase 5 を完了としてマークしないでください。スクリプトの出力全体を quality/results/quality-gate.log に追記してください。

v1.5.3 Layer-1 の機械的チェック（schemas.md §10 の不変条件 #1～#18）。 上記の従来のゲートチェックに加え、v1.5.3 の quality_gate.py では schemas.md §10 で定義されている Layer-1 の不変条件も適用されます。各不変条件の対象範囲を簡潔に示します。

• #1～#10 — コア契約チェック。 引用ティアのゲーティング、引用文書の存在、引用ハッシュの一致、引用抜粋の存在と位置特定（セクションまたは行のみ。ページだけでは不十分）、バグから REQ への解決、前方リンクの解決、処置の完全性、機能セクションの存在、孤立した正式文書がないこと、INDEX.md のフィールドの存在。
• #11 — 引用抜粋のバイト単位の一致。 ゲートでは、schemas.md §5.4 に従って bin/citation_verifier.extract_excerpt を再実行し、すべての Tier 1/2 の引用について、保存された citation_excerpt が新たに抽出されたものとバイト単位で一致しない場合は拒否します。これは Layer-1 のアンチハルシネーション機構です。実際のロケーターが存在していても、捏造または言い換えられた抜粋を検出します。
• #12 — schemas.md §3.4 に従った fix_type × disposition の有効な組み合わせ。
• #13 — schemas.md §1.6 に従ったマニフェストラッパーの妥当性。
• #14 — REQ のティアと引用先 FORMAL_DOC のティアの一致（Tier 1 の REQ が Tier 2 の FORMAL_DOC を引用することはできません）。
• #15 — 各マニフェスト内での ID の一意性。
• #16 — 冗長な引用メタデータ（version、date、url、retrieved）は、存在する場合、FORMAL_DOC と一致する必要があります。
• #17 — セマンティックチェックの多数決ルール。 同じ Tier 1/2 の REQ について、overreaches 判定が3件中2件以上あるとゲートは失敗します（Phase 4 の Layer 2 サブパスを参照）。
• #18 — 配列値の一意性。 REQ.use_cases と UC.formal_doc_refs が対象です。

citation_stale はゲートレポートのマーカーであり、引用レコードのフィールドではありません。 保存された citation.document_sha256 が、実際の FORMAL_DOC.document_sha256 と異なる場合、quality_gate.py は quality_gate_report.json（または同等のファイル）に citation_stale エントリーを書き込みます。引用レコード自体に citation_stale を書き込まないでください。レコードは入力のまま保持し、古さを示すマーカーは schemas.md §5.1 / §10 の不変条件 #3 に従い、ゲートレポートの出力とします。 この説明文でゲートを実装しないでください。 上記の Layer-1 チェックリストは、quality_gate.py が適用する内容の要約です。正式な定義は schemas.md に記載されています。ゲートの実装（v1.5.3 実装の Phase 5）は quality_gate.py にあります。SKILL.md はプロトコルを説明しますが、不変条件を再記載するものではありません。

ユースケース識別子の形式。 REQUIREMENTS.md では、すべての派生ユースケースに UC-01、UC-02 などの標準ユースケース識別子を使用する必要があります。各ユースケースには識別子を付けてください。機械可読なトレーサビリティを確保するために必須です。この識別子形式により、quality_gate.py と後続のツールでユースケースをプログラムからカウントし、相互参照できます。識別子のない散文形式の段落で記述されたユースケースは、要件に準拠していません。

PROGRESS.md を更新し、Phase 5 を完了としてマークしてください。BUG トラッカーには、すべての項目のクローズ状態が表示されている必要があります。

フェーズ終了時のメッセージ（必須 — Phase 5 の完了後にこれを出力し、その後停止してください）：

# Phase 5 Complete — Reconciliation and TDD Verification

All confirmed bugs now have regression tests, writeups, and TDD red-green verification.
[Summarize: N total confirmed bugs, N with TDD verified status, N with fix patches.
List all bug IDs with one-line summaries and their TDD verdicts.]

To continue to Phase 6 (Final verification and quality gate), say:

    Run quality playbook phase 6.

Or say "keep going" to continue automatically.

このメッセージを出力した後は、停止してください。ユーザーから明示的な依頼がない限り、Phase 6 に進まないでください。

---

Phase 6: 検証

v1.5.6 のインストルメンテーション： 今すぐ phase_start phase=6 を追記してください。フェーズ終了時に相互検証（quality/BUGS.md が空でなく、^## BUG- セクションを含むこと、および quality/INDEX.md が gate_verdict フィールドで更新されていること）を行い、その後 phase_end phase=6 を追記してください。Phase 6 の終了後、run_end status=success を追記してください（該当する場合は aborted または failed）。

このフェーズで必要な参照資料：

• references/verification.md — 45 件のセルフチェック用ベンチマーク

なぜ検証フェーズが必要なのですか？ AI が生成した出力は、洗練されて見えても、微妙な誤りを含んでいることがあります。未定義のフィクスチャを参照するテストは、失敗が 0 件でもエラーが 16 件発生することがあります。そして「失敗 0 件」は成功のように聞こえます。統合プロトコルに、実際のスキーマには存在しないフィールド名が記載されていることもあります。検証フェーズでは、ユーザーが問題を発見する前にこうした問題を検出します。生成された品質プレイブックへの信頼は脆弱であり、フィールド名を 1 つ誤るだけで、ほかのすべてに対する信頼が損なわれるため、これは重要です。

Phase 6 の実行モデル：一括ではなく段階的に実行します。 Phase 6 は、一連の独立した検証ステップとして実行します。各ステップでは、必要なファイルのみを読み込み、1 つの項目をチェックし、結果を次のステップに進む前に quality/results/phase6-verification.log に書き込みます。すべての成果物を一度にコンテキストへ読み込まないでください。成果物を読みながら、検証チェックリスト全体をメモリに保持しようとしないでください。以下の各ステップはそれぞれ独立しています。ファイルを読み、条件をチェックし、結果を追記して、コンテキストを破棄してください。

Step 6.1: 機械検証のクローズ処理（最初に必ず実行）

quality/mechanical/ が存在する場合、Phase 6 の文字どおり最初のアクションは次のとおりです。

bash quality/mechanical/verify.sh > quality/results/mechanical-verify.log 2>&1
echo $? > quality/results/mechanical-verify.exit

このコマンドをシェルで実行してください。Python スクリプトで代用したり、成果物ファイルを読み込んで内容を検証したり、このステップを省略したりしないでください。コマンドは bash quality/mechanical/verify.sh でなければなりません。python3 -c "..."、cat quality/mechanical/... | grep ...、その他の同等な方法ではいけません。

終了コードを記録してください。0 以外の場合、Phase 6 はただちに失敗となります。 それ以降のステップには進まないでください。抽出ステップに戻り、不一致の *_cases.txt を削除し、新しいシェルリダイレクトを使って抽出コマンドを再実行し、再検証したうえで、古い抽出結果を引用している後続の成果物をすべて更新してください。

PROGRESS.md の ## Phase 6 Mechanical Closure セクションに記録し、quality/results/phase6-verification.log に追記してください：

[Step 6.1] Mechanical verification: PASS (exit 0)

この手順を代替できない理由： v1.3.23 では、モデルが bash verify.sh を python3 -c "from pathlib import Path; ..." に置き換え、（偽造された）成果物ファイルを読み込んでその内容を検証しました。これは循環的なチェックであり、成果物が捏造されていても通過してしまいます。信頼できる唯一の検証方法は、成果物の生成に使われたものと同じシェルパイプラインを再実行し、その結果を差分比較することです。ほかの方法は、破損した中間ファイルによって欺かれる可能性があります。

Step 6.2: quality_gate.py を実行する（スクリプト検証済みチェック）

機械的な検証ゲートを実行します。

python3 quality_gate.py . > quality/results/quality-gate.log 2>&1  # locate via fallback (six canonical layouts, in order): quality_gate.py, .claude/skills/quality-playbook/quality_gate.py, .github/skills/quality_gate.py, .cursor/skills/quality-playbook/quality_gate.py, .continue/skills/quality-playbook/quality_gate.py, .github/skills/quality-playbook/quality_gate.py
echo $? >> quality/results/phase6-verification.log

quality/results/quality-gate.log を読みます。FAIL の結果が報告されている場合は、次に進む前に失敗したチェックをすべて修正してください。最もよくある FAIL は次のとおりです。（1）quality/patches/BUG-NNN-regression-test.patch ファイルがない、（2）bug_id ではなく id のような正規の JSON フィールド名になっていない、（3）TDD サマリーに confirmed_open がない、（4）インラインの修正差分を含まない報告書、（5）TDD の red/green ログファイルがない。quality_gate.py が 0 で終了するまで先に進まないでください。

quality/results/phase6-verification.log に追記します。

[Step 6.2] quality_gate.py: PASS (exit 0) — N checks passed, 0 FAIL, 0 WARN

このステップでは、検証ベンチマーク 14（サイドカー JSON）、17（テストファイルの拡張子）、18（ユースケース数）、20（報告書）、23（機械的な成果物）、26（バージョンスタンプ）、27（機械的なディレクトリ）、29（トリアージから BUGS への同期）、34（BUGS.md の存在）、38（個別の監査担当者レポート）、39（BUGS.md の見出し形式）、40（成果物ファイルの存在）、41（サイドカー JSON の検証）、42（スクリプト検証済みの完了）、43（ユースケース識別子）、44（回帰テストパッチ）、45（報告書のインライン差分）を対象とします。

v1.5.3 の Layer-1 不変条件もここで実行されます。 quality_gate.py はさらに、schemas.md §10 の不変条件 #1～#18（上記の Phase 5 で概要を説明）を適用します。特に、スクリプトは schemas.md §5.4 に従って、すべての Tier 1/2 引用について bin/citation_verifier.extract_excerpt を再実行し、保存された citation_excerpt が新たに抽出された出力とバイト単位で一致しない場合は拒否します。これは、取り込み後の改ざんを検出するためのチェックです。ここで Layer-1 不変条件に違反した場合は、根本原因となっているマニフェストレコードを修正し（ゲートや抜粋は修正しないでください）、再実行します。

Step 6.3: テスト実行の検証

機能テストスイートを実行します。テストコマンドを特定するため、quality/test_functional.* のみを読みます。

• Python: pytest quality/test_functional.py -v 2>&1 | tail -20
• Java: mvn test -Dtest=FunctionalTest または gradle test --tests FunctionalTest
• Go: 生成されたテストファイルのパッケージを対象に go test -v
• TypeScript: npx jest functional.test.ts --verbose
• Rust: cargo test
• Scala: sbt "testOnly *FunctionalSpec"

失敗とエラーの両方を確認します。フィクスチャの欠落、インポートの失敗、依存関係の未解決によるエラーは、テストの不具合として扱います。失敗が想定されている（xfail）回帰テストは、このチェックの対象外です。

quality/results/phase6-verification.log に追記します。

[Step 6.3] Functional tests: PASS — N tests, 0 failures, 0 errors

これは、ベンチマーク 8（すべてのテストがパスすること）および 9（既存のテストが壊れていないこと）を対象とします。

Step 6.4: 検証チェックリスト — ファイルごとの確認

references/verification.md にある残りの検証ベンチマークを、小さなバッチに分けて処理します。各バッチでは必要なファイルだけを読み、条件を確認して結果を追記してください。1つのバッチで読むファイルは2つまでにしてください。

Batch A — QUALITY.md（ベンチマーク 1-2、10）： quality/QUALITY.md を読みます。シナリオ数を数えます。各シナリオが実在するコードを参照していることを確認します（引用された関数名を grep します）。結果を追記します。

Batch B — 機能テストファイル（ベンチマーク 3-7）： quality/test_functional.* を読みます。バリアント間のカバレッジ（約30%）、境界テストの数、アサーションの深さ（値の確認と存在の確認）、レイヤーの正しさ（結果とメカニズム）、ミューテーションの妥当性を確認します。

Batch C — プロトコルファイル（ベンチマーク 11-13）： quality/RUN_CODE_REVIEW.md、次に quality/RUN_INTEGRATION_TESTS.md、次に quality/RUN_SPEC_AUDIT.md を、1つずつ読みます。それぞれが自己完結していて実行可能であることを確認します。統合テストの Field Reference Table を確認します。

Batch D — 回帰テスト（ベンチマーク 15-16、24）： quality/test_regression.* が存在する場合は読みます。スキップガードがバグ ID を参照していること、パッチ検証ゲートのコマンド、ソース検査テストで run=False が使われていないことを確認します。

Batch E — 列挙およびトリアージの確認（ベンチマーク 19、21-22、25、36）： quality/code_reviews/*.md の列挙セクションだけを読みます。quality/spec_audits/*triage* の検証プローブセクションだけを読みます。2つのリストの比較、実行可能なプローブの証拠、循環する機械生成アーティファクトへの参照がないこと、矛盾に対するゲートを確認します。

Batch F — 継続モード（ベンチマーク 32-33）： quality/SEED_CHECKS.md が存在する場合のみ実施します。これを読み、機械的な実行と、PROGRESS.md の収束セクションを確認します。

各バッチの結果を quality/results/phase6-verification.log に追記します：

[Step 6.4A] QUALITY.md scenarios: PASS — 8 scenarios, all reference real code
[Step 6.4B] Functional test quality: PASS — 30% cross-variant, assertion depth OK
[Step 6.4C] Protocol files: PASS — all self-contained and executable
[Step 6.4D] Regression tests: PASS — all skip guards present
[Step 6.4E] Enumeration/triage: PASS — two-list checks present, probes have assertions
[Step 6.4F] Continuation mode: SKIP — no SEED_CHECKS.md

いずれかのバッチが失敗した場合は、次のバッチに進む前に問題を直ちに修正します。

Step 6.5: メタデータの整合性チェック

quality/PROGRESS.md のメタデータとアーティファクト一覧のセクションだけを読みます。その後、以下を抜き取り確認します：

• 要件数が REQUIREMENTS.md のヘッダー、PROGRESS.md のアーティファクト一覧、COVERAGE_MATRIX.md のヘッダーの間で一致していること。3か所すべてで同じ数を記載する必要があります。
• With docs フィールドが reference_docs/ の有無を正確に反映していること
• Terminal Gate Verification セクションが存在し、記入済みであること

次に quality/COMPLETENESS_REPORT.md の判定セクションだけを読みます。調整前の古いテキストが残っていないことを確認します。## Verdict と ## Updated verdict（または ## Post-Review Reconciliation）の両方のセクションが存在する場合は、元の ## Verdict セクションを完全に削除します。最終文書には ## Verdict 見出しが1つだけ存在する必要があります。

quality/results/phase6-verification.log に追記します：

[Step 6.5] Metadata consistency: PASS — requirement counts match, version stamps consistent

メタデータが古い場合は、今すぐ修正します。

チェックポイント：PROGRESS.md の仕上げ

quality/PROGRESS.md を再度読みます。以下を更新します：

• Phase 6（検証ベンチマーク）を完了としてタイムスタンプとともに記録する

• BUG トラッカーのすべての項目が解決済みであることを確認する

• 最終サマリー行を追加する：「実行完了。BUG を N 件検出（コードレビューで N 件、仕様監査で N 件）。回帰テストを N 件作成。免除を N 件付与。」

• 次のプロンプトの候補をユーザーに提示します（必須、すべての実行で適用）。 これはベースラインを含む、すべての実行に適用されます。ユーザーがコピーして次のイテレーションを開始できるよう、以下のブロックを提示します：

  ベースライン実行（イテレーション戦略なし）の場合：

  ────────────────────────────────────────────────────────
  Next iteration suggestion:
  "Run the next iteration of the quality playbook using the gap strategy."
  ────────────────────────────────────────────────────────
  

  イテレーション実行の場合は、次の戦略を決めるために以下の対応表を使います：

  • gap → unfiltered を提案
  • unfiltered → parity を提案
  • parity → adversarial を提案
  • adversarial → 「品質プレイブックを最初から実行してください。」を提案（サイクル完了）

完成した PROGRESS.md は恒久的な監査証跡です。スキルが実施したこと、発見したこと、各発見への対処方法を記録します。ユーザーはこれを読んで実行内容を理解し、失敗をデバッグし、実行間の比較ができます。

収束チェック（継続モードのみ）

対象範囲： このサブセクションのみです。上記の次のプロンプト提案ステップは無条件であり、この収束チェックをスキップするかどうかにかかわらず、毎回実行する必要があります。

このステップは Phase 0 が実行された場合にのみ実行します（つまり、以前の実行の分析によって quality/SEED_CHECKS.md が存在する場合です）。以前の履歴がない初回実行の場合は、Phase 7 に進んでください。

今回の実行で検出されたバグのリストをシードリストと比較します。

1. 新規バグの数を数えます： 今回の実行の BUGS.md にあるバグのうち、どのシードとも（ファイルと行番号で）一致しないものを数えます。「新規」バグとは、過去のどの実行でも見つかっていないバグです。
2. シードの持ち越し数を数えます： 今回の実行で再確認されたシード（Step 0b で FAIL の結果となったもの）を数えます。
3. 解決済みシードの数を数えます： 現在はテストに合格しているシード（前回の実行以降にバグが修正されたもの）を数えます。

PROGRESS.md に ## Convergence セクションを書き込みます。

## Convergence

Run number: N (N prior runs in quality/previous_runs/)
Seeds from prior runs: S (S confirmed, R resolved)
Net-new bugs this run: K
Convergence: [CONVERGED | NOT CONVERGED]

Net-new bugs:
- BUG-NNN: [summary] (file:line) — not in any prior run

収束の判定基準： 新規バグ数 = 0 の場合、実行は収束しています。つまり、今回の実行で見つかったすべてのバグが、以前の実行ですでに把握されていたことになります。宣言されたスコープ内で、これ以上実行しても追加のバグが見つかる可能性は低いということです。

収束している場合： ユーザーに「今回の実行では、以前の実行ですでに把握されていた N 件を超える新しいバグは見つかりませんでした。このスコープのバグ検出は収束しました。すべての実行で確認されたバグの合計：T 件。」と表示します。その後、Phase 7 に進みます。

収束していない場合 — 自動で再反復します。 収束チェックで新規バグ数が 0 より大きく、反復回数が最大値（デフォルト：5）に達していない場合、スキルは自動的に再反復します。

1. 反復番号と新規バグ数を PROGRESS.md に記録します。
2. bin/run_playbook.archive_previous_run(repo_dir, timestamp) を介して（または Phase 6 の成功時に bin.archive_lib.archive_run() を介して）現在の quality/ ディレクトリをアーカイブします。これらは quality/ を quality/previous_runs/<timestamp>/quality/ にスナップショットし、実行ごとの INDEX.md と RUN_INDEX.md の行を作成します。
3. Phase 0 から再開します（これにより、quality/previous_runs/ に新たにアーカイブされた実行が検出されます）。
4. ユーザーに「反復 N で K 件の新しいバグが見つかりました。アーカイブして反復 N+1 を開始します（最大 M 回）。」と表示します。

反復カウンターは初回実行で 1 から始まります。アーカイブして再開するたびに 1 ずつ増加します。カウンターが最大値に達した場合、収束していなくても反復を停止し、「最大反復回数（M 回）に達しましたが、収束しませんでした。最後の実行で K 件の新しいバグが見つかりました。すべての実行で確認されたバグの合計：T 件。」と表示します。

反復回数の制限。 デフォルトの最大反復回数は 5 回です。ユーザーのプロンプトに明示的な制限（例：「プレイブックを 3 回反復して実行」）が含まれている場合は、その制限を使用します。ユーザーのプロンプトに「1 回のみ」または「反復なし」とある場合は、再反復を完全にスキップし、反復前の動作と同様に、収束していない場合は新規バグ数を表示して再実行を提案します。

コンテキストウィンドウへの配慮。 再反復中のいずれかの時点で、コンテキストウィンドウが大幅に消費されていると判断した場合（例：以前の反復よりも明らかに出力が短くなったり、品質が低下したりしている場合）は、反復を停止し、現在の状態を PROGRESS.md に書き込み、「コンテキストの制約により反復を停止します。M 回中 N 回の反復が完了しました。続行するにはプレイブックを再実行してください — Phase 0 が quality/previous_runs/ からシードリストを取得します。」と表示します。これは安全弁であり、目標ではありません。ほとんどのコードベースは 2～3 回の反復で収束します。

重要な理由： 1 回のプレイブック実行で、コードベースの一部が非決定論的に調査されます。virtio での初回実行では BUG-001 と BUG-004 が見つかっても、BUG-005 は見逃される可能性があります。2 回目の実行では BUG-005 と BUG-006 が見つかるかもしれません。3 回目までに新しいバグが現れなければ、重要度の高い領域はおおむね調査できたと考えられます。シードリストにより、以前に見つかったバグが実行間で失われることはなく、収束チェックによって追加実行の効果が薄れていることをユーザーに知らせます。自動再反復によりスキルは自己完結します。収束させるために、呼び出し元が外部スクリプトや手動での再実行を行う必要はありません。

フェーズ終了時のメッセージ（必須 — Phase 6 完了後にこれを表示し、停止してください）：

# Phase 6 Complete — All Phases Done

The quality playbook baseline run is complete. Here's the summary:

[Include: total confirmed bugs, quality gate pass/fail/warn counts,
list of all bug IDs with one-line summaries and severities.]

Key output files:
- quality/BUGS.md — all confirmed bugs with spec basis and patches
- quality/results/tdd-results.json — structured TDD verification results
- quality/patches/ — regression test and fix patches for every bug

You can now run iteration strategies to find additional bugs. Iterations typically
add 40-60% more confirmed bugs on top of the baseline. The recommended cycle is:
gap → unfiltered → parity → adversarial.

To run all four iterations automatically, say:

    Run all iterations.

I'll orchestrate each strategy as a separate sub-agent with its own context window.

To run one iteration at a time, say:

    Run the next iteration of the quality playbook.

Or ask me about the results: "Tell me about BUG-001" or "Which bugs are highest priority?"

After you fix the bugs, say "recheck" to verify the fixes were applied correctly.

このメッセージを出力した後、停止してください。ユーザーが明示的に指示しない限り、イテレーションを続行しないでください。

イテレーション終了メッセージ（必須 — 各イテレーションの完了後に出力し、その後停止してください）：

# Iteration Complete — [Strategy Name]

[Summarize: N net-new bugs found in this iteration, total now at N.
List new bug IDs with one-line summaries.]

[If there are remaining strategies in the recommended cycle, suggest the next one:]
The next recommended strategy is [next strategy]. To run it, say:

    Run the next iteration using the [next strategy] strategy.

[If all four strategies have been run:]
All four iteration strategies have been run. Total confirmed bugs: N.
You can review the results, ask about specific bugs, or re-run any strategy.

After you fix the bugs, say "recheck" to verify the fixes were applied correctly.

Or say "keep going" to run the next iteration automatically.

このメッセージを出力した後、停止してください。ユーザーが明示的に指示しない限り、次のイテレーションに進まないでください。

---

再確認モード — バグ修正の検証

再確認モードは、前回の実行で見つかったバグが修正されたかを確認する、軽量な検証パスです。6 フェーズのパイプライン全体（60～90 分）を再実行する代わりに、既存の quality/BUGS.md を読み込み、現在のソースツリーに照らして各バグを確認し、修正済みか未解決かを報告します。通常、再確認には 2～10 分かかります。

再確認モードを使う場合： ユーザー（または別のエージェント）が、プレイブックで見つかったバグの修正を適用した後に使います。ユーザーが「再確認」または「バグ修正を検証して」または「どのバグが修正されたか確認して」と指示した場合です。

再確認モードを、プレイブック全体の実行の代わりに使わないでください。 再確認で検証するのは以前見つかったバグだけです。新しいバグは検出しません。

再確認手順

ステップ 1：バグ一覧を読み込みます。

quality/BUGS.md を読み込み、すべての ### BUG-NNN エントリーを解析します。各バグについて、以下を抽出します。

• バグ ID（例：BUG-001）
• **File:** フィールドにあるファイルパスと行番号
• 説明の概要（**Description:** の最初の文）
• 重大度
• **Fix patch:** フィールドにある修正パッチのパス（例：quality/patches/BUG-001-fix.patch）
• 回帰テストのパス（**Regression test:** フィールド）

ステップ 2：現在のソースに照らして各バグを確認します。

各バグについて、以下の確認を順番に実施します。

1. 修正パッチの確認。 参照先に修正パッチが存在する場合、現在のツリーに対して git apply --check --reverse quality/patches/BUG-NNN-fix.patch を実行します。逆適用が成功した場合（終了コード 0）、修正パッチはすでに適用されています。バグは修正済みの可能性があります。失敗した場合、修正は適用されていないか、コードが変更されています。

2. ソースの調査。 指定された行番号のファイルを開きます。前後 20 行程度のコンテキストを読みます。確認した内容をバグの説明と比較します。問題のあるコードは変更されていますか？修正はバグ報告に記載された根本原因に対処していますか？

3. 回帰テストの実行。 回帰テストのパッチが存在する場合：

   • 適用します：git apply quality/patches/BUG-NNN-regression-test.patch
   • テストを実行します（プロジェクトのテストランナーを使用）。テストが成功すれば、バグは修正されています。失敗すれば、バグはまだ存在しています。
   • パッチを元に戻します：git apply -R quality/patches/BUG-NNN-regression-test.patch

   回帰テストのパッチをきれいに適用できない場合（ソースが変更されているため）、その旨を記録し、ソースの調査のみで判断します。

4. 判定。 以下のいずれかのステータスを割り当てます。

   • 修正済み（FIXED） — 修正パッチが適用され、回帰テストが成功した場合（またはテストを実行できない場合に、ソースの調査で修正を確認できた場合）
   • 一部修正済み（PARTIALLY_FIXED） — 問題のあるコードは変更されているものの、回帰テストが失敗する場合、または修正がバグの一部にしか対処していない場合
   • 未解決（STILL_OPEN） — 元の問題のあるコードが変更されていない場合、または回帰テストが失敗する場合
   • 判定不能（INCONCLUSIVE） — ステータスを判断できない場合（ファイルが移動された、コードが大幅にリファクタリングされた、パッチを適用できない）

ステップ 3：再確認結果を生成します。

次のスキーマで quality/results/recheck-results.json を書き込みます。

注：再確認スキーマでは "schema_version": "1.0" を使用します（TDD サイドカーで使う "1.1" ではありません）。これは構造が異なるためです。source_run とバグごとの status／evidence フィールドは再確認スキーマ固有のものです。品質ゲートはこの値が "1.0" であることを検証します。

{
  "schema_version": "1.0",
  "skill_version": "1.5.6",
  "date": "YYYY-MM-DD",
  "project": "<project name>",
  "source_run": {
    "bugs_md_date": "<date from BUGS.md header>",
    "total_bugs": <N>
  },
  "results": [
    {
      "id": "BUG-001",
      "severity": "HIGH",
      "summary": "<one-line summary>",
      "status": "FIXED",
      "evidence": "<what confirmed the fix — e.g., 'reverse-apply succeeded + regression test passes'>"
    }
  ],
  "summary": {
    "total": <N>,
    "fixed": <N>,
    "partially_fixed": <N>,
    "still_open": <N>,
    "inconclusive": <N>
  }
}

また、人が読める形式の概要を quality/results/recheck-summary.md に書き込みます。

# Recheck Results

> Recheck of quality/BUGS.md from <date>
> Recheck run: <today's date>
> Skill version: <version>

## Summary

| Status | Count |
|--------|-------|
| Fixed | N |
| Partially fixed | N |
| Still open | N |
| Inconclusive | N |
| **Total** | **N** |

## Per-Bug Results

| Bug | Severity | Status | Evidence |
|-----|----------|--------|----------|
| BUG-001 | HIGH | FIXED | Reverse-apply succeeded, regression test passes |
| BUG-002 | MEDIUM | STILL_OPEN | Original code unchanged at quality_gate.py:125 |
| ... | ... | ... | ... |

## Still Open — Details

[For each STILL_OPEN or PARTIALLY_FIXED bug, include a brief explanation of what remains to be fixed.]

ステップ 4：再確認の概要を出力します。

概要テーブルをユーザーに出力し、その後停止します。例：

# Recheck Complete

Checked 19 bugs from quality/BUGS.md against current source.

| Status | Count |
|--------|-------|
| Fixed | 17 |
| Still open | 2 |
| **Total** | **19** |

Fixed bugs: BUG-001, BUG-002, BUG-003, BUG-004, BUG-005, BUG-006, BUG-007,
BUG-008, BUG-009, BUG-010, BUG-011, BUG-013, BUG-014, BUG-015, BUG-016,
BUG-017, BUG-018

Still open: BUG-012 (stale .orig file still present), BUG-019 (benchmark 40
artifact list not updated)

Results saved to:
- quality/results/recheck-results.json (machine-readable)
- quality/results/recheck-summary.md (human-readable)

再確認モードの実行

ユーザーが「recheck」「verify the bug fixes」「check which bugs are fixed」「recheck the bugs」「run recheck mode」など、あるいは新しいバグの発見ではなく修正の確認を希望していることが明確に分かる表現を使った場合、再確認モードが有効になります。トリガーされたら、フェーズ 1～7 はすべてスキップし、上記の再確認手順のみを実行してください。

---

フェーズ 7：提示、探索、改善（対話形式）

生成と検証が完了したら、結果を分かりやすく提示し、次に何をするかをユーザーが選べるようにします。このフェーズは、ひと目で分かる要約、必要に応じた詳細の確認、改善方法のメニューという 3 つのパートで構成されます。

このフェーズを省略しないでください。 フェーズ 1～6 で自律的に生成された成果物は確かな出発点ですが、ユーザーが何を生成したのかを理解し、関心のある内容を確認し、改善方法を選べるようにする必要があります。プロジェクトの担当者が信頼し、内容を理解できてこそ、質の高いプレイブックは役に立ちます。説明なしに 6 つのファイルを出力しても、誰にも読まれない成果物ができるだけです。

パート 1：要約テーブル

ユーザーが 10 秒で把握できるテーブルを 1 つ提示します。

Here's what I generated:

| File | What It Does | Key Metric | Confidence |
|------|-------------|------------|------------|
| REQUIREMENTS.md | Testable requirements with use cases | N requirements, N use cases | ██████░░ Medium — solid baseline from 5-phase pipeline, improves with refinement passes |
| QUALITY.md | Quality constitution | 10 scenarios | ██████░░ High — grounded in code, but scenarios are inferred, not from real incidents |
| Functional tests | Automated tests | 47 passing | ████████ High — all tests pass, 35% cross-variant |
| RUN_CODE_REVIEW.md | Three-pass code review | 3 passes | ████████ High — structural + requirement verification + consistency |
| RUN_INTEGRATION_TESTS.md | Integration test protocol | 9 runs × 3 providers | ██████░░ Medium — quality gates need threshold tuning |
| RUN_SPEC_AUDIT.md | Council of Three audit | 10 scrutiny areas | ████████ High — guardrails included |
| RUN_TDD_TESTS.md | TDD verification protocol | N bugs to verify | ████████ High — mechanical red-green cycle with spec traceability |

実際に生成したものに合わせてテーブルを調整してください。ファイル名、メトリクス、信頼度はプロジェクトによって異なります。最も重要なのは信頼度の列です。ユーザーがどこに注目すべきかを示します。

信頼度のレベル：

• 高 — コード、仕様、スキーマから直接導き出されたものです。修正が必要になる可能性は低いです。
• 中 — 妥当な推論ですが、誤っている可能性があります。ユーザーからの情報があると役立ちます。
• 低 — 最善の推測です。有用なものにするには、必ずユーザーからの情報が必要です。

テーブルの後に、各成果物を実行するための、そのままコピーできるプロンプトを含む「クイックスタート」ブロックを追加します。

To use these artifacts, start a new AI session and try one of these prompts:

• Run a code review:
  "Read quality/RUN_CODE_REVIEW.md and follow its instructions to review [module or file]."

• Run the functional tests:
  "[test runner command, e.g. pytest quality/ -v, mvn test -Dtest=FunctionalTest, etc.]"

• Run the integration tests:
  "Read quality/RUN_INTEGRATION_TESTS.md and follow its instructions."

• Start a spec audit (Council of Three):
  "Read quality/RUN_SPEC_AUDIT.md and follow its instructions using [model name]."

• Run TDD verification for confirmed bugs:
  "Read quality/RUN_TDD_TESTS.md and follow its instructions to verify all confirmed bugs."

テストランナーのコマンドとモジュール名は、実際のプロジェクトに合わせて調整してください。重要なのは、ユーザーがコピーして貼り付けられるプロンプトを提供することです。実行できる内容の説明ではなく、ユーザーが実際に入力するテキストを記載してください。

クイックスタートブロックの後に、次の一文を追加します。

「これらについて詳しく知りたい場合は、どれについてでも質問できます。たとえば、『シナリオ 3 を見せて』や『統合テストマトリックスについて順を追って説明して』と尋ねてください。」

パート 2：必要に応じた詳細の確認

ユーザーが特定の項目について尋ねた場合、ファイル全体ではなく、重要な判断内容と不確かな点に絞って要約します。例：

• 「シナリオ 4 について教えて」 → シナリオのテキストを示し、その根拠（どの防御パターンまたはドメイン知識か）を説明し、推論した点と把握している点を明示します。
• 「統合テストマトリックスを見せて」 → 実行グループを示し、並列化の方針を説明し、スキーマから導き出した品質ゲートと推測した品質ゲートを明記します。
• 「機能テストはどのように動作しますか？」 → 3 つのテストグループを示し、仕様およびシナリオとの対応関係を説明し、特に信頼度の低いテストを強調します。

ユーザーは改善に進む準備ができるまで、何度か詳細を尋ねることがあります。それで問題ありません。ユーザーのペースで確認できるようにしてください。

パート 3：改善メニュー

ユーザーに要約を提示した後（任意で詳細を確認してもらった後）、改善オプションを提示します。

「改善する方法は 5 つあります。」

1. 要件を対話形式で確認する — quality/REVIEW_REQUIREMENTS.md を読み、ユースケース別に整理された要件を順を追って確認します。特定のユースケースを選んで詳しく確認することも、すべてを順番に確認することもできます。別のモデルに完全性レポートの事実確認を依頼することもできます（モデル間監査）。適しています：パイプラインが見落としたギャップの発見。

2. 別のモデルで要件をブラッシュアップする — quality/REFINE_REQUIREMENTS.md を読み、ブラッシュアップを実行します。Claude、GPT、Gemini など、任意の AI モデルで実行でき、それぞれ異なるギャップを見つけます。効果が薄れてくるまで、必要なだけモデルを実行してください。各回の実行前に現在のバージョンがバックアップされ、変更内容は quality/VERSION_HISTORY.md に記録されます。適しています：要件をベースラインから完全な状態に近づけること。

3. ほかの項目を確認して強化する — 任意のシナリオ、テスト、プロトコルのセクションを選んでください。一緒に確認します。適しています：特定の品質ゲートの強化、推測に基づくシナリオの修正、欠けているエッジケースの追加。

4. ガイド付き Q&A — コードから推測できなかったインシデントの履歴、想定される分布、コスト許容度、モデルの好みなどについて、的を絞った質問を 3～5 個します。適しています：シナリオの信頼性を高めるナレッジギャップの解消。

5. 追加ドキュメントを提供する — 要件パイプラインは、意図を示す情報源が多いほど効果を発揮します。以下のいずれかを指定してください。要件と品質の憲章のブラッシュアップに活用します。

• エクスポートした AI チャット履歴（Claude、Gemini、ChatGPT のエクスポートデータ、Claude Code のトランスクリプト）
• プロジェクトについて議論した Slack または Teams のチャンネル
• プロジェクトに関するメールのスレッド、Jira／Linear のチケット、または GitHub の Issue
• 設計ドキュメント、アーキテクチャ決定記録、または議事録
• ニュースグループへの投稿、フォーラムの議論、またはメーリングリストのアーカイブ

Claude Cowork、GitHub Copilot、OpenClaw などのツールを使ってこれらの情報源に接続し、フォルダーにまとめてから、そのフォルダーを指定できます。適しています：推測ではなく、実際のプロジェクト履歴に基づいてシナリオと要件を作成すること。

「これらは、どのような組み合わせでも、どのような順番でも実施できます。どれから始めますか？」

各改善パスの実行

パス 1：要件を対話形式でレビューする。 quality/REVIEW_REQUIREMENTS.md をユーザーに案内し、一緒に内容を確認することを提案します。このプロトコルでは、セルフガイド（ユースケースを選択）、完全ガイド（順を追って確認）、クロスモデル監査（別のモデルが完全性レポートの事実確認を行う）をサポートしています。進捗は quality/REFINEMENT_HINTS.md に記録されるため、ユーザーは前回の続きから再開できます。

パス 2：別のモデルで要件を改善する。 quality/REFINE_REQUIREMENTS.md をユーザーに案内します。各改善パスでは、現在のバージョンを quality/history/vX.Y/ にバックアップし、REFINEMENT_HINTS.md からフィードバックを読み取り、対象を絞って改善し、マイナーバージョンを上げ、VERSION_HISTORY.md に変更を記録します。ユーザーは Claude、GPT、Gemini など、任意のモデルで実行できます。モデルごとに異なる見落としを検出できます。改善効果が薄れるまで実行します。

パス 3：ほかの項目をレビューして強化する。 ユーザーがシナリオ、テスト、プロトコルのセクションを選びます。現在のテキストを示し、判断の根拠を説明して、内容が正確かを確認しながら進めます。ユーザーからのフィードバックに基づいて修正します。機能テストを変更した場合は、テストを再実行します。

パス 4：ガイド付き Q&A。 調査で実際に見つけた内容に基づいて、3～5 個の質問をします。次のカテゴリは、最もよく見られる効果の高い不足項目を網羅しています。

• シナリオに関するインシデント履歴。 「[具体的な防御コード] が見つかりました。どのような障害が原因でしたか？ 影響を受けたレコードは何件ですか？」
• 品質ゲートのしきい値。 「[フィールド] に [値] が含まれていることを確認しています。通常の分布はどのようなものですか？ 何が問題の兆候ですか？」
• 統合テストの規模とコスト。 「プロトコルでは [N] 件のテストが実行され、費用はおよそ $[X] です。カバレッジを増やすべきですか、減らすべきですか？」
• テスト範囲。 「[N] 件の機能テストを生成しました。既存のテストスイートでは [その他の領域] をカバーしています。不足している領域はありますか？」
• 仕様監査に使うモデルの好み。 「どの AI モデルを使っていますか？ 特定の強みを感じたことはありますか？」

ユーザーの回答後、生成されたファイルを修正し、テストを再実行します。

パス 5：追加のドキュメントを取り込む。 ユーザーから、チャット履歴、Slack のエクスポート、メールのスレッド、Jira チケット、設計ドキュメント、議事録、フォーラムのアーカイブなど、意図を示す追加の情報源を案内してもらいます。これらには、正式なドキュメントに反映されていない設計上の決定、インシデント履歴、品質に関する議論が含まれています。

1. インデックスファイルを探し、品質に関連する内容を確認します（ステップ 0 と同じ方法ですが、今回は対象が具体的です。根拠を補う必要のある要件、しきい値が必要なシナリオ、解消すべき不足項目が分かっています）。
2. 次の内容を抽出します。具体的な数値を伴うインシデントの経緯、防御パターンの設計根拠、品質フレームワークに関する議論、クロスモデル監査の結果、コードだけでは分からなかった動作上の契約。
3. 調査結果を新しいフィードバック項目として quality/REFINEMENT_HINTS.md に追加し、改善パスを実行して要件を更新します。
4. QUALITY.md のシナリオを実際のインシデントの詳細に基づいて修正します。統合テストのしきい値を実環境の値に更新します。修正後にテストを再実行します。

ユーザーがステップ 0 ですでにチャット履歴を提供している場合は、その内容をすでに調査しています。ただし、特定の会話を案内してもらったり、情報源を追加したり、特定のトピックをさらに詳しく調べるよう依頼されたりする場合があります。

反復

ユーザーはこれらのパスを好きなだけ繰り返せます。各パスを経るたびに、品質プレイブックの実態に即した内容が増えていきます。ユーザーが納得したら、明示的な「完了」ステップなしで自然に次へ進みます。

フィクスチャ戦略

quality/ フォルダーは、プロジェクトのユニットテスト用フォルダーとは別です。プロジェクトの言語に適したテストセットアップを作成してください。

• Python： pytest フィクスチャ用の quality/conftest.py。フィクスチャをテスト内で直接定義する場合（pytest の tmp_path パターンでよく使われます）は、共有フィクスチャよりもそちらを優先してください。
• Java： @BeforeEach／@BeforeAll セットアップメソッドを持つテストクラス、または共有テストユーティリティクラス。
• Scala： テスト仕様にミックスインするトレイト（例：trait FunctionalTestFixtures）、またはインラインのデータビルダー。
• TypeScript/JavaScript： beforeAll／beforeEach フックを含む quality/setup.ts、またはインラインのテストファクトリー。
• Go： 同じ _test.go ファイル内のヘルパー関数、または共有の testutil_test.go。テストヘルパーには t.Helper() を使用してください。Go の慣例では、共有フィクスチャよりもインラインのテストセットアップが好まれます。
• Rust： #[cfg(test)] mod tests ブロック内のヘルパー関数、または共有の test_utils.rs モジュール。テストデータにはビルダーパターンを使用してください。

既存のテストファイルを調べ、テストデータのセットアップ方法を把握してください。既存のテストで使われているパターンをそのまま採用してください。現実的なデータ構造にするため、既存のフィクスチャパターンを確認してください。

---

用語

• 機能テスト — コードが仕様に記載された出力を生成するかを確認します。個々の関数を単独で検証するユニットテストとは異なります。
• 統合テスト — 実際の外部サービスも含め、コンポーネントがエンドツーエンドで連携するかを確認します。
• 仕様監査 — AI モデルがコードを読み、仕様と比較します。コードは実行しません。コードがドキュメントと一致していない箇所を検出します。
• カバレッジ至上主義 — 高いカバレッジ数値を出すものの、実際のバグを検出できないテストです。例：出力を確認せず、関数が例外をスローしなかったことだけをアサートする。
• 目的適合性 — 実環境の条件下で、コードが本来の目的を果たすかを確認します。システムのカバレッジが 95% でも、記録が気づかれないまま失われることがあります。

---

原則

1. カバレッジ率よりも目的適合性を重視する
2. シナリオはコードの調査とドメイン知識の両方から導き出す
3. 具体的な障害モードによって基準を譲れないものにする — 抽象的な要件は都合のよい解釈を招く
4. ガードレールによって AI レビューの品質を高める（行番号、本文を読む、主張する前に grep する）
5. 修正の前にトリアージする — 多くの「欠陥」は仕様のバグか設計上の判断である
6. 構造的レビューには上限がある（約 65%）。残りの約 35% は意図への違反、つまり欠落のバグ、ファイル間の矛盾、設計上の不備であり、コードだけを読むツールでは検出できない。要件によって、見えないものを見えるようにする
7. 独自の貢献となるのは仕様であり、レビュー構造ではない。意図のソースから導き出した、適切でテスト可能な要件を用意することが、重点領域やレビュー手順よりも重要である
8. 要件間の一貫性チェックは不可欠である。バグは、個別には正しい 2 つのコード間の隙間に潜んでいることが多い。要件ごとの検証だけでは、こうしたバグは見つけられない
9. 導出した要件はすべて残す — 絞り込まない。要件を 1 つ余分に確認するコストは低く、バグを検出できたはずの要件を削ったためにバグを見逃すコストは高い
10. バグが存在することを示す最も強い証拠は、失敗するテストである。修正パッチがある確認済みのバグごとに、レッド・グリーンの TDD サイクル（バグのあるコードではテストが失敗し、修正済みのコードでは成功する）を実行する。FAIL→PASS の出力を提示する — レビュー担当者は修正に異議を唱えることはできても、再現するテストには反論できない

---

参照ファイル

各フェーズを進める際に、以下を参照してください。

ファイル	読むタイミング	内容
references/exploration_patterns.md	フェーズ 1（探索）	パターンの適用可能性マトリクス、詳細調査用テンプレート、ドメイン知識に関する質問
references/defensive_patterns.md	ステップ 5（検出結果の骨子作成）	Grep パターン、検出結果をシナリオに変換する方法
references/schema_mapping.md	ステップ 5b（スキーマの型）	フィールドマッピングの形式、変更の妥当性ルール
references/requirements_pipeline.md	フェーズ 2（要件）	5 フェーズのパイプライン、バージョニングプロトコル、引き継ぎルール
references/constitution.md	ファイル 1（QUALITY.md）	セクションごとのガイダンスを含む完全なテンプレート
references/functional_tests.md	ファイル 2（機能テスト）	テスト構成、アンチパターン、バリアント横断の戦略
references/review_protocols.md	ファイル 3～4（コードレビュー、統合）	両プロトコル用のテンプレート、パッチの検証、スキップガード
references/spec_audit.md	ファイル 5（3 者協議）	完全な監査プロトコル、トリアージプロセス、修正の実行
references/iteration.md	イテレーション（フェーズ 6 の後）	4 つのイテレーション戦略：ギャップ、フィルターなし、パリティ、敵対的
references/verification.md	フェーズ 6（検証）	構造化出力、パッチゲート、スキップガードの検証、事前調査、バージョンスタンプ、バグ報告、列挙の完全性、実行可能なトリアージ証拠、コードから抽出した列挙リスト、機械的検証アーティファクト、ソース検査テストの実行、矛盾ゲート、シードチェックの実行、収束の追跡、サイドカー JSON スキーマ検証、スクリプトで検証する完了ゲート、正規のユースケース識別子、報告へのインライン修正差分を含む完全なセルフチェックリスト（45 項目）