gap-trap

gap-trap

エージェントがコードの大半を記述するリポジトリ向けに、品質フレームワークを構築します。エージェントが守るすべてのルールにはゲートがあり、ルールに違反するとコミット、プッシュ、または CI の実行が失敗します。スクリプトで確認できるのに、対応するゲートがないルールは欠陥です。このフレームワークについては reference/framework.md に記載されています。どちらのモードを実行する場合も、先にお読みください。

モードは 2 つです。setup は、まだフレームワークがないリポジトリにフレームワークを構築します。 refine は、フレームワークがあるリポジトリを監査し、問題が発生した箇所をもとに、次のルールとゲートを提案します。キーワードなしで gap-trap を実行すると、リポジトリに AGENTS.project.md がない場合は setup、ある場合は refine が実行されます。手書きの AGENTS.md や CLAUDE.md だけでは、フレームワークが存在することにはなりません。これらは setup の入力として扱われます。

モデルゲート

このスキルは、ハーネスの最上位コーディングモデルで実行します。Claude Code では Opus、またはそれ以上の能力を持つモデル（Opus 4.8 以降、Opus 5、Fable、Mythos）、Codex では高または xhigh の推論強度に設定した最先端のコーディングモデルを使用してください。コードベースのどの部分にコントラクトを適用するかはディスカバリーで決まるため、コントラクトを誤ると、その後のすべてのセッションに影響します。システムプロンプトには使用中のモデルが記載されています。

より安価または高速なモデル（Sonnet、Haiku、mini モデル、または推論強度が低いモデル）を使用している場合は、停止してください。何も読まず、何も書かないでください。次のとおり正確に伝えて、ターンを終了してください。

gap-trap は、このハーネスの最上位コーディングモデルで実行します。現在のモデルは です。/model で切り替えてから、gap-trap をもう一度実行してください。

弱いオーケストレーターから、より強力なサブエージェントを呼び出したり、「簡単な部分」から始めたり、簡易版を提案したりしないでください。

setup

1. 検出します。 reference/discovery.md に従います。スクラッチディレクトリに計画ファイルが作成されます。計画には、スタック、コマンド、CI プロバイダー、実際のシンボル名を使った契約候補、履歴から得られた最初のドメイン上の事実（revert probe はコミット数にかかわらず実行されます）、既存の指示ファイルで見つかったルールごとの行（適用先とゲートを含みます）が記載されます。
2. 一度だけ確認します。 計画を短いリストで提示します。作成する契約（最大 6 件）、追加するゲート、見つかったテストと lint のコマンド、移行済みルールの表、slop-mop の配置先を示します。すでに失敗しているビルド、型チェック、lint がある場合は、それを最初の項目にします。セットアップでは、そのゲートに必要なもの（不足している型パッケージやロックファイルなど）だけを修正し、残りはラチェットのカウントまたは対象外項目として記録します。失敗しているものを記録する前に、それぞれの原因を明らかにします。再現し、失敗内容を読み、何が壊れているのかを説明します。環境変数を示すエラーでも、コードの不具合である場合があります。ある試行では、Environment variable not found: DATABASE_URL により 7 件のテストが失敗しましたが、原因は .env の不足ではなく、テスト対象のモジュールの読み込み後に Prisma モックが読み込まれたことでした。これを環境の問題として記録していたら、バグと、それを防ぐ契約を見落としていたでしょう。検出だけでは解決できなかった点についてのみ、質問を一度行います。その後、作業を進めます。
3. slop-mop をインストールします。 スクラッチディレクトリに git clone https://github.com/pliablepixels/slop-mop.git を実行し、slop-mop/slop-mop を実行中のハーネスのスキルディレクトリ（Claude Code の場合は ~/.claude/skills/、Codex の場合は ~/.agents/skills/）にコピーします。すでに存在する場合はスキップします。リポジトリにはベンダー同梱しません。AGENTS.project.md のプロジェクトルールで必須とされています。ハーネスはセッション開始時にスキル一覧を読み込むため、この作業でインストールしたスキルは、インストールした実行中には利用できません。この実行では、AGENTS.md に P10 の文章を記述し、レポートでユーザーに、slop-mop は次のセッションから適用されると伝えます。
4. templates/ を使って指示ファイルを作成します。 AGENTS.md と agents/generic/agent-workflows.md は変更せずにコピーします。ただし、このリポジトリには存在し得ないゲートに関するルール（UI のないリポジトリにおける I3 のアクセシビリティ lint と C3 のロケール）については、Gate: 節を Gate: n/a, no <thing> in this repo に置き換えます。AGENTS.md のそれ以外の箇所は変更しません。AGENTS.project.md、CLAUDE.md、agents/project/ は計画に基づいて記入します。リポジトリに UI がない場合は、UI とエンドツーエンドに関する行、および {{E2E_CMD}} を削除します。検証済みの値で埋められないプレースホルダーはすべて削除します。契約には実在するシンボル名のみを記載します。既存の指示ファイル（AGENTS.md、CLAUDE.md、.cursorrules、.github/copilot-instructions.md、CONTRIBUTING.md）は、計画の移行済みルール表に従い、1 行ずつ移行します。契約の行は契約ブロックに、ルールの行はゲート名または Gate: review を付けたプロジェクトルールに、プレイブックの行は指定された agents/project/ ファイルにそのまま、コマンドの行は検証ブロックに反映し、重複または削除対象の行は含めません。ルールを黙って削除することはありません。確認の段階で表を提示します。テンプレートが所有する名前のファイル（AGENTS.md、CLAUDE.md）は、そのテンプレートで置き換えます。それ以外の指示ファイル（.cursorrules、.github/copilot-instructions.md）は、エージェントが古いコピーではなくルールを参照するよう、AGENTS.md への 1 行のポインターにします。CONTRIBUTING.md は元の場所に残します。ユーザーには差分を提示します。
5. reference/gates.md を使ってゲートを作成します。 リポジトリ独自のテストランナーと CI プロバイダーを使い、指示ゲート、再現済みの失敗、PR 本文チェック、ラチェット（常に追加し、リポジトリで対応するカウンターを初期値に設定します。C2 の長さを超えるファイル、linter 実行時のルールごとの lint 問題数、現時点で違反のある各契約の Never 条項を対象とします）、および、検出時にリスクの高いモジュール（auth、パーサー、API クライアントなど）が特定された場合はミューテーションスモークを作成します。該当しない場合は、最初の修正チェーンの後に refine が追加します。スタック表で参照先を選びます。Node と Python にはネイティブポートを、その他のすべての言語には git、grep、awk のみを必要とするシェル版を使います。指示ゲートの語数上限は、現在の語数の 1.5 倍を次の 500 単位に切り上げた値に設定します。
6. 各ゲートの失敗を実証します。 スクラッチ用の違反を作り、その違反を削除し、リポジトリの全テストコマンドを実行します。そのうえで、次の順序でコミットごとに論理的変更を 1 つずつコミットします。まず、指示ファイルとそれを検査するゲートをまとめてコミットします。その後は、ラチェット、再現済みの失敗、ミューテーションスモーク、PR 本文チェックの各ゲートをそれぞれ別のコミットにします。続いて、ゲートをまとめて実行するコマンドと pre-commit フックをコミットし、最後に CI をコミットします。フレームワーク全体を 1 つのコミットにまとめると、どのゲートが何に対して失敗を実証したのかが分からず、個別に戻せる変更も残りません。依頼がない限り、push しないでください。
7. レポートします。 作成したもの、指示ファイルの語数と上限、Gate: review とした契約とその理由、今回の実行で slop-mop をインストールしたか、した場合は次のセッションから適用されることを報告します。リポジトリ外で常時読み込まれるファイルに、リポジトリ内の文章スタイルと相反する記述（~/.codex/AGENTS.md、~/.claude/CLAUDE.md、簡潔すぎるスタイルや圧縮されたスタイルなど）があれば、ファイル名を挙げ、リポジトリ内の文章にはリポジトリのルールが適用されると伝えます。最後に、次の手順を 1 つだけ記します。最初のインシデント後、または 1 か月後に gap-trap refine を実行してください。
8. チェックを提案します。 レポートの最後に、次の質問を 1 つだけします。新しいフレームワークに照らして、今すぐリポジトリをチェックしますか？「いいえ」の場合は終了します。「はい」の場合は、ファイルを一切変更せず、契約 ID またはルール ID ごとにまとめて、次の内容を列挙します。
   • 各ラチェットカウンター、その件数、および各件数の根拠となるファイルと行。
   • 各 Gate: review 契約について、その Path: 行と Never: 行が対象とするコードを読み、疑わしい違反をファイルと行とともに列挙します。ゲートによるチェックがないため、未検証であることを明記します。
   • 手順 2 で記録した、失敗しているビルド、型チェック、lint の項目。 この確認では何も修正しません。ユーザーが選んだ修正は独立したコミットにします。件数を減らす修正では、--update を指定してラチェットを再実行します。 指示ファイルはエージェントが読みます。ID とゲート名を付け、簡潔な文で記述してください。 人向けの文章はリポジトリのドキュメントに記載し、AGENTS*.md や agents/ には記載しないでください。

refine

reference/refine.md に従ってください。ゲートのないルール、存在しなくなったコントラクト名、前回の refine 以降のコミット履歴を監査し、自己改善プロトコルを通じて編集を提案し、1 つの PR にまとめます。ゲートを追加するのと同じように、根拠となるインシデントがないルールも削除します。

よくある間違い

間違い	修正
シンボル名を推測したコントラクト	Path: 行のすべての名前はツリー内で grep できます。そうでなければ指示ゲートは失敗します
初日に 10 個のコントラクトを書く	承認済みの手順が 1 つだけあり、現時点で違反がある箇所から始め、残りは refine を通じて追加します
初回実行で合格したゲート	まず一時的な違反を作って失敗を確認します。一度も失敗しないゲートは何の証明にもなりません
slop-mop をリポジトリに同梱する	slop-mop は各エージェントのリポジトリからインストールされます。プロジェクトルールでそれを必須にします
人向けに整えた指示文	読むのはエージェントです。文、理由を 1 つ含む節、ゲート名にします
リポジトリが小さいからとモデルゲートを省略する	提供するのは探索の質です。ゲートが最初にあるのには理由があります