調査対象リストと観点リストの生成・更新

codepatrol skillの指揮役から任されて、.dev/codepatrol/ の調査対象リスト targets.md と、観点リスト checklist.md を生成・更新する。 どちらを生成・更新するかは、指揮役の指示に従う。

このskillを実行する時の前提

• 実行環境の条件は codepatrol skill の「実行環境の確認」と同じである。着手する前に自分でも確認し、満たさなければ何も生成せず、満たさない条件を報告して終了する
• ユーザーに質問できない。判断がつかない事は、最後の報告に書く
• リポジトリごとのコードを読む場所と、.dev/codepatrol/ の場所は、指揮役の指示に従う。関連リポジトリがある時は、その名前と領域名の接頭辞も指揮役の指示に従う。branchの切り替え・pull・commitはしない

設定ファイルの形式

targets.mdとchecklist.mdの冒頭に Format: {現在の値} を書く。現在の値は2である。 形式はskillの更新で変わる。どちらかのファイルの値が現在の値と違うか無い時、指揮役は両方の更新を任せる。形式が違う既存のファイルを更新する時は、新しい形式で作り直し、既存の領域・機構の事実・固有の観点を引き継ぐ。観点は番号ではなく内容で対応付ける。Format の記録が無い旧形式では固有の観点がマスターの番号列を続けていたので、同じ番号が別の観点を指す。マスターへの補足で表せない旧項目は、固有の観点として残す。関連リポジトリの一覧が無い旧形式のファイルでは、既存の領域を設定を置くリポジトリの物として引き継ぐ。

targets.md の生成・更新

調査領域には2つの種類がある。

• 入口起点の領域: サーバー側のエントリポイントを走査して検出する。入口単体の保護を主担当にする
• 利用終了イベント起点の領域: 利用・所属・契約・権限・連携が終わる、または縮小するイベントで切る。入口起点の領域には「あるはずの処理が無い」事を指摘する主担当が居ないので、イベントで切った領域が、入口の間・保存先の間の整合を主担当にする

設定を置くリポジトリでは、自動検出の対象はサーバー側に限定している。 client/config/infraなど他の領域が必要な場合は、ユーザーがtargets.mdに手動で追加する。

関連リポジトリ

同じサービスを構成する別のリポジトリを、指揮役が関連リポジトリとして渡す事がある。関連リポジトリごとに、設定を置くリポジトリと同じ入口起点の走査を行い、領域名を指揮役から渡された接頭辞で始めて、どのリポジトリの領域かを区別する。領域の本文の先頭に「リポジトリ: {名前}」と、対になる別のリポジトリの領域があればその名前を書く。対になる領域は、同じ入口やデータを両側から扱う領域で、アップロードの受付とバイナリの保存のように、リポジトリの境界で役割が分かれている物である。パスは、その領域のリポジトリのrootからの相対で書く。

インフラ設定のように、サーバー側の入口を持たない関連リポジトリでは、入口の代わりに、外部に影響する設定の単位で領域を切る。秘密情報と権限の定義、ネットワークの到達範囲、デプロイの定義、データストアの構成といった単位である。何がどこまで設定に書かれ、何がリポジトリの外にあるかを、領域の本文に書く。

利用終了イベント起点の領域には接頭辞を付けない。イベントはリポジトリの境界をまたぐので、単位は関連リポジトリのデータモデルからも列挙し、同じ単位の入口と資産をリポジトリをまたいで1つの領域にまとめる。関連リポジトリがある時、この領域のパスには常にリポジトリ名を添える。

クライアントのリポジトリは、自動検出の対象外で、領域はユーザーが手動で足す。

走査の中で、関連リポジトリに入っていない別のリポジトリの手掛かりを見つけたら、候補として最後の報告に挙げる。別のサービスのホスト名やAPI client、deploy定義が参照する別のイメージ、クライアントの配布や更新の仕組みが手掛かりになる。候補に領域は作らない。

入口起点の領域

リポジトリの構成を調査して調査領域を検出する:

1. package.json、Gemfile、go.mod等からフレームワークとサーバー側コードの位置を把握する
2. サーバー側のエントリポイント、つまり外部からの入力を受け付ける箇所を列挙する。リポジトリに存在するものだけでよい:
   • HTTPルーティングと、それが参照するcontroller・ハンドラ群
   • WebSocket等のリアルタイム通信のハンドラ群
   • 認証・認可・CSRF・rate limit等の横断的なmiddleware・フィルタ
   • webhook受信、バッチ・ジョブ等、上記に含まれない外部入力の入口

領域のグルーピング指針:

• controller・ハンドラを収めたディレクトリは原則1ディレクトリ = 1領域
• 単体ファイルのcontrollerは関連するものをまとめてよい
• 認証・認可等の横断的なmiddleware・フィルタは1領域にする
• WebSocket等のリアルタイム通信は1領域にする

利用終了イベント起点の領域

データモデルから、終了・縮小のイベントがある単位を列挙する。典型は、利用者アカウント、チーム・プロジェクト・組織といったテナント、契約・プラン、画像・ページ・ファイルといった主要なリソースである。単位ごとに1領域にし、名前は lifecycle- で始める。調査の担当は、この接頭辞で調査の手法を切り替える。

各領域の本文には次を書く:

• 起点イベントの入口。Web・API・管理画面・ジョブ・外部サービスからの通知を含める。終了だけでなく、メンバーの除外・プランの降格・連携の解除といった縮小も含める。約束や規約にあるのに入口が見つからないイベントも、見つからない事を書いて含める
• 開始側。終了時の扱いを確かめる資産・権限・連携が、どこで作られるか
• 期待値の出典。利用者への約束が書かれた表示箇所と、リポジトリ内の保持方針・設計の文書。表示箇所は画面の文言・利用規約・ヘルプ・管理画面の注意書き等で、言語ごとに表現が違う事があるので併記し、本文がリポジトリ外にある物はその旨を書く
• 関連する領域。ファイルが重なる領域。lifecycle領域同士の重なりと、関連リポジトリの領域も書く

lifecycle領域はファイルを他の領域と共有する。その事をtargets.mdの冒頭に書く。指揮役が並列に調査する組を決める材料になる。

書き出し

検出した領域を .dev/codepatrol/targets.md に書き出す。領域名はファイル名やページタイトルの一部になるため、英数字・ハイフン・アンダースコアに収め、パス区切りや空白を含めない。フォーマット:

# Codepatrol Investigation Targets

Format: {現在の値}
Generated at: {YYYY-MM-DD HH:mm:ss}
Generated by: {Agent名 (model名)}, with {Codexの実行環境}
Source commit: {設定を置くリポジトリの、読んだcommitのshort hash}
Source commit ({関連リポジトリ名}): {そのリポジトリの、読んだcommitのshort hash}

各H2見出しが調査領域名。この名前がレポート名の一部になる。
領域を追加・分割・統合する場合はこのファイルを手動で編集する。

`lifecycle-` で始まる領域は利用終了イベントで切った領域で、ファイルは他の領域と重なる。

**関連リポジトリ**: 以下のリポジトリも調査の対象で、領域名の接頭辞で区別する。cloneの場所は開発者ごとに違うので、このファイルには書かない。

- {関連リポジトリ名}: {1行の役割}。領域名は `{接頭辞}-` で始まる。 {GitHub URL}

## {領域名}

{対象ディレクトリ/ファイルのパス}
{主なファイルの列挙}

## {接頭辞}-{領域名}

リポジトリ: {関連リポジトリ名}。{対になる別のリポジトリの領域と、役割の分かれ方}

{そのリポジトリのrootからの相対パス}
{主なファイルの列挙}

## lifecycle-{単位}

{単位と、終了・縮小のイベントの説明}

- 起点イベントの入口: {入口の列挙}
- 開始側: {資産・権限・連携が作られる場所}
- 期待値の出典: {表示箇所・言語・適用イベント}
- 関連する領域: {ファイルが重なる領域名}

関連リポジトリが無い時は、Source commit ({関連リポジトリ名}) の行と、関連リポジトリの段落を省く。

既存のtargets.mdを更新する時:

既存のtargets.mdを読み込み、新しい走査結果と比較する。

• 既存のH2見出し（領域名）は保持する。ユーザーが手動で分割・統合した結果を壊さない
• 既存のH2見出し配下の説明文は、走査結果に基づいて最新化してよい
• 新たに検出された領域はH2見出しを末尾に追加する
• 走査結果に該当しなくなった領域（ディレクトリ削除等）は削除せず残す。ユーザーが判断して削除する
• 指揮役の指示で関連リポジトリを外した時は、そのリポジトリの領域をヘッダの一覧と一緒に削除する。既存のレポートはそのまま残る

checklist.md の生成・更新

このSKILL.mdと同じディレクトリにある CHECKLIST.md は、特定のリポジトリに依存しない観点のマスターで、書き換えない。 .dev/codepatrol/checklist.md はリポジトリ固有の層で、調査の担当はマスターと一緒に読む。マスターの観点の文は写さない。写すと、skillの更新で観点が変わった時に古い文が残る。

1. CHECKLIST.md を読み込む
2. リポジトリのセキュリティ機構を調査する。認可middlewareとロール階層の具体名、テナント境界の単位（プロジェクト・チーム・組織等）、認証・session管理の方式、テンプレートエンジンとクライアント描画の方式、DBアクセス層、ファイルストレージ、外部にリクエストを送る箇所、rate limitの実装、課金等のビジネスロジック
   • 関連リポジトリがあれば、それぞれの機構も同じ目で調査する。リポジトリ間の呼び出しで、どちらが認証・認可を担い、何を信頼して受け取るかも機構の事実として押さえる
   • この調査の目的は観点に具体名を補うことであり、問題の検出は調査の担当が行う。個々の実装の深追いはしない
   • 既存の調査レポートがあれば、機構を把握する情報源として活用する
   • 利用終了時に残りうる資産も調べる。関連リポジトリにある資産も、リポジトリ名を添えて同じ一覧に並べる。targets.mdの lifecycle-* 領域の単位ごとに、その単位の識別子を持つデータと、そこから所有関係や生成経路で辿れる間接的な資産を列挙する。関連の宣言だけに頼らない。関連で結ばれていないモデル、ログ、外部サービスに作った物、子の先にある孫の資産は、識別子と生成経路から探さないと落ちる。原本・派生・退避・一時保存・検索indexやキャッシュやキュー・ログや解析の複製・外部サービス・利用者端末・バックアップを区別し、cascadeやdependentのようにコードに書かれた既定の扱いまでを事実として並べる。各イベントで実際にどうなるかは書かない。調査の担当が確かめる
3. 調査結果を .dev/codepatrol/checklist.md に書き出す:
   • 冒頭に Format、Source commit、Generated by: {Agent名 (model名)}, with {Codexの実行環境} を記録する。Source commit はtargets.mdと同じく、リポジトリごとに行を分ける。構成把握がどの時点・どのmodelによるものかを診断可能にする
   • 調査で把握した機構の要約を「このリポジトリのセキュリティ機構」セクションとしてまとめる。ライブラリはバージョン数字を省いて名前だけ書く。利用終了時に残りうる資産は、このセクションの中に「利用終了時に残りうる資産」の節として置く。関連リポジトリの機構は「関連リポジトリのセキュリティ機構」の節に、リポジトリごとの小節で置く
   • 「観点への補足と固有の観点」に、マスターの観点ごとに、このリポジトリでの具体名を書く。middleware名、関数名、ディレクトリ等である。リポジトリに無い仕組みの観点は、非該当と理由を書く。関連リポジトリがある時は、具体名・非該当の判定・固有の観点が、どのリポジトリに当てはまるかが分かるように書く
   • リポジトリ固有の仕組みに対する観点は、該当カテゴリに {カテゴリ記号}+{番号} で足す。マスターの番号と混ざらないためである。レポートの見出しと、調査の担当がCodexに相談する時のグループ分けが、カテゴリの記号を参照する

フォーマット:

# Codepatrol Checklist ({設定を置くリポジトリ名})

Format: {現在の値}
Source commit: {設定を置くリポジトリの、読んだcommitのshort hash}
Source commit ({関連リポジトリ名}): {そのリポジトリの、読んだcommitのshort hash}
Generated by: {Agent名 (model名)}, with {Codexの実行環境}

マスターのCHECKLIST.mdと一緒に読む。ここには、設定を置くリポジトリと関連リポジトリに固有の事だけを書く。

## このリポジトリのセキュリティ機構

### {機構の区分}

### 利用終了時に残りうる資産

### 関連リポジトリのセキュリティ機構

#### {関連リポジトリ名}

## 観点への補足と固有の観点

### {カテゴリ記号}. {カテゴリ名}

- {観点番号}: {具体名。関連リポジトリがあれば、どのリポジトリの物かを添える}
- {観点番号}: 非該当。{理由}
- {カテゴリ記号}+{番号}. **{固有の観点名}**: {観点}

既存のchecklist.mdを更新する時:

既存のchecklist.mdを読み込み、リポジトリの機構を再走査して、機構の事実・観点への補足・固有の観点の追加・更新を行う。

checklistの領分:

checklistに書くこと・書かないことは checklist-vs-report.md に従う。仕様・機構の説明と中立な観点だけを書く。特定の問題の断定・深刻度・悪用仮説・レポートの問題への言及は書かない。 既存のchecklist.mdに、この境界に合わない記述が入り込んでいれば、仕様事実または中立な観点に書き直すか、削除する。

codex-consultationによるリストのレビュー

targets.mdまたはchecklist.mdを生成・更新したら、2つまとめてcodex-consultationでレビューする。 一方だけを更新した場合も、両方を渡す。 このレビューは省略も代替もできない。

Skill toolで codex-consultation を呼び出す。codex exec の直接実行で済ませない。Argsには以下を含める:

Args: よく相談して。このリポジトリの開発チームが、自分たちのコードの問題を検出して修正するためにセキュリティ調査をしている。その調査に使う調査対象リストと観点リストを作成した。以下の2つのファイルをレビューしてほしい。

- 調査対象リスト: {.dev/codepatrol/ の絶対パス}/targets.md — 見落としているエントリポイント、領域の分け方と粒度。`lifecycle-*` の領域については、見落としている終了・縮小のイベントと入口、期待値の出典
- 観点リスト: マスター {CHECKLIST.mdの絶対パス} と、リポジトリ固有の層 {.dev/codepatrol/ の絶対パス}/checklist.md — 見落としている観点、非該当とした観点の妥当性、補った具体名の誤り。「利用終了時に残りうる資産」の節については、見落としている資産と、既定の扱いの誤り

コードの場所: {リポジトリごとの絶対パス}

指摘を受けたら自分でコードを読んで検証し、妥当な指摘をファイルに反映する。 checklist.mdへの反映は checklist-vs-report.md の境界に従い、問題寄りの指摘は取り込まない。

Generated by には自分のAgent名とmodel名を記入し、codex-consultationが取得したCodexの実行環境を併記する。レビューだけをやり直した時は、生成したAgentの記録を保ち、Codexの実行環境だけを更新する。

Codexが停止した場合:

usage limit・spend cap・認証エラー・通信障害等でCodexが最終回答を返さずに終了した場合は、他の手段で代替しない。通信障害のような一時的なエラーなら、数分待って1〜2回は再試行してよい。usage limitやspend capはすぐには解消しないので再試行しない。 生成したファイルはそのまま残し、Generated by に「Codexレビュー未実施」と記録して、何のエラーで止まったかを報告して終了する。

指揮役への報告

• 生成・更新したファイルと、読んだリポジトリごとのcommit
• targets.mdの領域の一覧。更新の場合は、足した領域と、走査結果に該当しなくなった領域
• 関連リポジトリの候補と、その根拠
• checklist.mdで足した観点、非該当とした観点、書き直した記述
• Codexの指摘のうち、反映した物と、反映しなかった物とその理由
• 判断がつかなかった事