integration-contract

統合契約

仕様のリポジトリ間の接合点を契約ファイルとしてディスクに書き込み、スモークゲートでチェックします。名目上は単一プロジェクトの仕様でも、以下のコンシューマー調査を実施します。

入力

<SPEC-ID> — 仕様（PRD）／親課題の識別子です。コンテキストから取得するか、一度だけ尋ねてください。ユーザーが不在で、推測できる情報もない場合は、Needs-user の注記を残して停止します。どの仕様かを推測してはいけません。

ルール

• 帰属情報を一切記載しない。 どの出力にも共著者、AI、ツールの帰属情報を追加または残してはいけません。このルールを契約にも含めてください。
• 環境の権限。 デフォルトではローカルのテスト環境を使用します。本番環境には絶対にアクセスしないでください。ステージング環境の利用には明示的な承認とユーザー提供のアクセス権が必要です。変更を伴う操作には、それぞれ個別の承認が必要です。ホストが不明、または権限がない場合、該当するフローは pending のままにします。
• 単一プロジェクトでも調査を実施し、信頼だけで済ませない。 仕様が1つの PROJECT-CODE にのみ関係する場合、変更対象のサーフェスについて、他の Project Matrix リポジトリにある呼び出し箇所を調査します（以下の範囲を絞った検索を参照）。外部の呼び出し箇所が見つからず、どこにもコンシューマーが特定されない状態で調査が完了した場合は、「single project — no contract needed」と報告して停止します。ファイルを作成してはいけません。過去の契約は保持して報告し、そのゲートログを削除しないでください。外部の呼び出し箇所が見つかった場合、仕様にかかわらず接合点はプロジェクト間にまたがります。契約を作成し、そのようなコンシューマーをそれぞれリスク行として記録してください。
• 範囲を絞った検索のみ。 references/consumer-sweep.md に従い、変更対象の各サーフェスをすべての Project Matrix リポジトリで検索します。リポジトリ全体や specs/ ツリーをまとめて読み込んではいけません。コンシューマーは file:symbol 形式で記載してください。利用できないリポジトリがある場合、調査は未完了となります。リスクを記録し、契約が不要だと結論づけてはいけません。
• 意図と実装を区別する。 記録された決定を確認するために GLOSSARY.md（旧称 CONTEXT.md）と関連する ADR を読みます。実際の動作を把握するために現在のコードを追跡します。仕様または現在のユーザー決定と矛盾する点は、リスク行として記録してください。ネイティブ CLI のメモは、検証すべき手がかりです。
• 決定は成果物として残す。 チャットでは、書き込んだ内容とフェーズ更新のみを報告します。
• すべての箇所で Project Matrix に記載された完全な PROJECT-CODE を使用します。あるプロジェクトの規約、トークン、コンポーネントを別のプロジェクトに持ち込んではいけません。
• コンシューマーが特定されない場合も、合格ではなくリスク。 プロジェクト間契約では、変更対象のサーフェスに関してマトリックス内のどこにも呼び出し箇所が見つからない場合、または仕様の対象スライス外にコンシューマーがある場合、RISK 行を記載します。未使用だと黙って仮定してはいけません。
• フローの判定には、検証済み環境が必要です。 証拠のない合格は pass ではなく pending のままにします。
• 提案にとどめ、自動で次の処理を開始しない。 build は gate を自動実行しません。gate は /commit-push-* を自動実行しません。次の手順を推奨して停止します。
• build では読み取り専用。 書き込めるのは契約ファイルのみです。プロダクトコード、設定、課題、ADR は変更してはいけません。
• サブエージェント：独立した作業にはローカルのレーンを自動で割り当てます。クラウドエージェントを使ってはいけません。割り当て時にレーン数を告知し、各レーンの完了時に報告します。

契約成果物

仕様ごとに1つ、<artifacts-root>/specs/integration/<SPEC-ID>-contract.md に作成します。<artifacts-root> は、存在する場合は *.code-workspace のディレクトリ、そうでなければコンテキスト単位のルート（リポジトリルートの GLOSSARY-MAP.md、旧称 CONTEXT-MAP.md）、それもなければリポジトリルートに解決します。

再実行時は既存の契約を読み込み、ユーザーの編集とゲートログを保持し、実装または環境が変わったフローを pending に戻します。<SPEC-ID> は、パス区切り文字や .. を含まない、単一のファイル名構成要素として検証します。

build モードでは references/build-contract.md を記入します。gate モードでは既存の契約を使用し、構造またはスモークテストの網羅範囲の修復が必要な場合にのみスキーマを読み込みます。不確かな場合は、記入済みの例を任意で参照できます：references/contract-example.md。

モード

build（デフォルト）

1. 仕様とそのサブイシューを読みます。
2. 変更された PROJECT-CODE を検出します。該当がちょうど 1 つの場合は、単一プロジェクトのスイープ（Rules）を実施し、コントラクトが不要になった時点で停止します。
3. プロデューサーのスライスとそのコンシューマーを特定し、セクション 1～3 を埋めます。仕様の対象外のコンシューマーがある場合は、/to-tickets でスライスを提案します。
4. セクション 4 のフローを記述します（Driver、空の Evidence、Status: pending）。ファイルを書き込み、build の更新を出力します。

gate

完全な gate では、仕様レベルの出荷とPM への引き継ぎを対象とします。未実装のスライスをまたぐフローは、スライス単位の /commit-push-* を妨げません。交差する部分が実装済みのフローは早めに実行し、残りは pending のままにします。

1. 何かを実行する前に、環境を確認します（セクション 1）。ホストの権限、サービスへの到達性、必要なテストデータ、変更された対象が実行中のアーティファクトに含まれていることを確認します。上記の権限内でのみ再ビルドまたはデータの投入を行います。それ以外の場合は、該当するフローを pending のままにします。フローを実行する前に、セクション 2～3 を実装と照合し、変更された対象を更新します。
2. Driver に従って各フローを実行し、Evidence（スクリーンショットのパス、引用した応答、確認できたテキスト）を記録して、pass／fail を設定します。ブラウザーのフローでは、references/consumer-sweep.md に従います。
3. fail が 1 つでもあれば、コントラクトを再開します。 記録して共有し、現在の手順をブロックします。commit-push せず、PM に引き継がず、失敗を黙って取り除くことも決してしません。失敗した接続箇所は /to-tickets に送るか、スライスの欠落ではなく欠陥の場合は /diagnosing-bugs に送ります。
4. Driver を利用できない場合（agent-browser がインストールされていない場合、または現時点で実行できない手動手順の場合）は、その旨を記載し、該当するフローをユーザー向けの手動手順として列挙して、pending のままにします。想定に基づいてフローを pass にすることは決してありません。
5. pending の件数と理由を含めた gate-log の行を追記します。すべてが pass の場合は、/code-review の後に /commit-push-close／/commit-push-pr、または PM への引き継ぎを提案します。fail がある場合は /to-tickets または /diagnosing-bugs を提案します。pending が 1 つでもあれば、仕様レベルの出荷と PM への引き継ぎをブロックし、不足している証跡を報告します。停止し、自動で次の処理に進むことはありません。

出力

各フェーズの移行時に Stage / Found / Next / Needs user を出力します。各フィールドを 1 行ずつ記載します。

build update：

Stage: build — wrote specs/integration/<SPEC-ID>-contract.md. [or: single project — no contract needed (matrix swept; no external call-sites)]
Found: producer <PROJECT-CODE>; consumers <PROJECT-CODE>, <PROJECT-CODE>; <K> changed surfaces; <R> risk row(s). [or: matrix swept for <K> changed surfaces; no external call-sites]
Next: implement the slices, then integration-contract gate mode before spec-level ship and PM handoff. [or: proceed per-slice — no integration gate needed]
Needs user: <risk rows to confirm, environment facts, or "none">.

gate report — Section 4 の表（Evidence を除く）に Status を記入し、次の行の間に配置します。

Environment: <verified service(s) and artifact evidence, or unverified service(s) and reason>.
<table>
Reopened by failures (blocking, not shipped): <#s or "none">.

Suggested next skills (optional):
- /to-tickets: slice the failing seam (<#s>).
- /code-review then /commit-push-*: once every flow is pass.

完了条件

• コントラクトが 4 つのセクションと gate log を備えて再開されていること。または、build update が single project — no contract needed となっており、新しいファイルが書き込まれておらず、過去のコントラクトが保持され、特定されていること
• gate：新しい gate-log の行が追記されていること。すべてのフローの Status が pass／fail で Evidence が記入されているか、pending であること
• 出力された update が、実行したモードの Output テンプレートと一致していること