project-audit

プロジェクト監査 — 現時点でこのプロジェクトについて何が真実か

ゲートが問うのは、成果物が良好かどうかです。受け入れ確認が問うのは、リストにあるものが失われていないかどうかです。どちらも、プロジェクトが今実際にどのような状態かは問いません。1 か月触れていなかったリポジトリを開いたとき、運用担当者が知りたいのはそれだけです。

このスキルは、コールドスタートからその問いに答えます。ブリーフも、REQ テーブルも、モジュールマップも必要ありません。そして、2 つの成果物を残します。人が読むページと、次の監査が読むサイドカーです。

目次

• これは何ではないか
• 6 つのフェーズ
• 3 つの判定と、3 つ目が存在する理由
• バージョン確認では見えない種類
• 2 つの成果物
• スクリプトが行うことと、あなたが行うこと
• 終了基準
• 合理化

これは何ではないか

	担当するもの	使う場面
references/portable-method.md	手法 — L0→L7 の段階、境界、軸のローテーション	1 回の実行中に 1 つの成果物を確認する場合
このスキル	手順 — コールドスタート、調査、レポート作成	プロジェクト全体が対象の場合
/skill-audit (make-skill)	スキルが標準に準拠して構築されているか	監査対象がスキルまたはプラグインの場合
/ux-audit (super-ux)	文書化されたシナリオに対するコードの検証	ユーザー向けの挙動が問いの場合
/seo-aeo-audit (seo-aeo-audit)	公開されているものの、検索エンジンと回答エンジンに対する可視性	マシンに見つけられるかどうかが問いの場合

フェーズ 4 の前に references/portable-method.md を読んでください。 このドキュメントには単独で使える監査の最低基準が記載されており、同じ階層のスキルもネットワークアクセスも必要ありません。コンパニオンのタスクパイプライン監査、バックログ、優先順位付けに関するリファレンスは、インストールされていればさらに深く読むための任意資料です。これらがなくても、この手順が妨げられることはありません。

6 つのフェーズ

順番に実行します。各フェーズは、レポートの生成元となる同じペイロードに書き込みます。

1. 発見 — 測定を始める前に、このプロジェクトが何であるかを把握する

scripts/audit.py がこれに機械的に答えます。言語、パッケージマネージャー、モノレポの構成、サブモジュール、CI、デプロイ先、宣言されているテレメトリー、プロジェクト自身が示すバージョンを調べます。コミット済みの状態を読み取ります。git ls-files を使い、ディレクトリを走査することはありません。ディレクトリの走査では node_modules やビルドの残骸まで見つかり、クローンでは生成されないプロジェクトを報告してしまうためです。

出力はプロファイルであり、そのプロファイルに基づいて調査項目を選びます。これを省略して固定チェックリストを実行すると、どのリポジトリに対しても同じ 9 件の指摘が出る監査になってしまいます。

2. 調査 — プロファイルに基づいて選ぶレジストリ

各調査項目は、必要なもの（git、gh、npm、network、接続済み MCP サーバー）を宣言します。要件が満たされていない場合、その調査項目は理由とともに確認不能になります。決して「該当なし」にも「問題なし」にもなりません。スタック別のカタログと、スクリプトが対応していないプロジェクト構成で追加する項目については、references/probes.md を参照してください。

3. 本番環境 — リポジトリの外にしか存在しない証拠

これは多くの監査で省かれるフェーズであり、リポジトリが自分自身について認められないことを見つけるフェーズです。

• 公開済みの成果物とソースの比較 — 次のセクションを参照してください。
• CI の履歴：「成功しているか」ではなく、リリース実行のうち失敗した割合と、失敗が検知されたかどうかを確認します。gh run list --limit 60 --json conclusion,name は 1 つのコマンドで実行でき、パッケージにとって本番環境のログに最も近いものです。
• テレメトリーの有無。何かがデプロイされている場合に限り、テレメトリーがないことは所見になります。ライブラリの場合は設計上の選択です。いずれの場合も、レポートではどちらなのかを明記します。「Sentry が設定されていない」と「エラーがない」を同じ意味にしてはいけません。
• 採用状況。レジストリで提供されている場合は、ダウンロード数によって「本番環境で使われているか」を意見ではなく測定結果として示せます。
• 接続済みの MCP サーバー — エラートラッカー、分析、ホスティング、データベースなどです。プロジェクトが何を使っているかを尋ね、接続済みのものを使い、残りは盲点として記録します。集計値と参照先を読み、生の本文は決して読みません（2 つの成果物を参照）。

データストアを読み取る前に、必ず次の順序で確認してください — 誤ったデータベースから得た数値は、測定値としての権威を伴って引用されるため、数値がないよりも悪いものです。

1. リポジトリ内のスクリプトやドキュメントに記載された名前ではなく、プラットフォーム自身のアタッチメントからデータストアを特定します。
2. 製品が継続的に書き込むテーブルを対象に、最新の書き込み時刻の集計値を使って稼働中であることを確認します。そのタイムスタンプを、それが裏付けるすべての数値の横にレポートへ記載します。
3. 複数のデータストアが接続されている場合は、すべてのデータストア名とそれぞれの最新時刻を記載します。1 つを読み取り、もう 1 つに触れない監査は、読者が再現できません。
4. リポジトリの接続ヘルパーが示すのはリポジトリについての証拠であり、プラットフォームについての証拠ではありません。両者の食い違い自体が所見であり、このルールが定められた理由でもあります。

4. 境界 — 段階的な手順へ引き継ぐ

ここまで来て初めて、そしてここまで来てからのみ、ローカルのポータブルな手法の段階的な手順を、調査で見つかった機能に適用します。下から上へ、境界の順に進めます。ここで見つかった不在も、ほかの所見と同じく所見です。

5. レポート — 2 つのファイル、1 つのコマンド

python3 scripts/audit.py --root <path> はサイドカーを作成し、概要を出力します。HTML ページを作成するには --report を追加し、開かずに書き出すには併せて --no-open を指定します。プローブもこのスクリプトに含まれているため、レポートが主張する内容と実行された内容は同じものです。

6. 提案 — 編集ではなく行

このスキルは何もコミットしません。 所見はプロジェクト独自の用語でボードの行として出力され、ボードヘッダーで宣言された計算式に基づいて優先度が付けられます。出荷時の既定値は Sev × Blast + age_bonus（references/portable-method.md、ローカルの優先度に関する契約）です。採用するかどうかはオペレーターが判断します。監査では工数による順位付けは行いません。修正にかかるコストを決めるのは発見者ではなく、修正担当者です（references/portable-method.md）。読み取りながら編集する監査では、自分自身を検証するために再実行できません。task-pipeline の wave モードでは、これらの行と JSON サイドカーが wave 0 の入力となり、id によってそのインベントリに追加されます。

評価項目は各軸を分けて記述する必要があります。そうでなければ、判定を装った推測です

メカニズムのステータス、悪用／再現性、露出、観測された発生頻度、影響の不確実性は、ひとつではなく5つの軸です。 メカニズムだけをもとに記述された項目は、各軸が把握していることを示すまで、実際の評価項目と見分けがつきません。ある監査では、測定によって連続する8件の項目が書き直されました。そのうち2件は、どちらも販売がないことを需要がないことと読み違えていたため、記載どおりに対処していたら在庫を損なうところでした。ただし、この修正は両方向に働きます。

• 欠陥が証明されていても、発生頻度は不明の場合があります。 ローカルで再現された認証バイパスや競合状態は、インシデントが起きる前からコードの欠陥です。再現できることが証拠であり、その項目を記載するために本番ログは必要ありません。本番ログがなく、ローカルでのクラッシュが確認されている場合も、コードの欠陥であり、外部での発生頻度は不明です。
• 不明 ≠ 0です。 サンプルがゼロでもリスクがゼロとは限りません。テレメトリがない場合に低くなるのは、露出について言えることだけであり、技術的な事実ではありません。その違いを項目に記載します。
• 攻撃者による制御が不明なら、悪用可能性への確信度は下がりますが、観測された挙動は変わりません。実際に起きているところを観測したのであれば、そのとおりに記載します。
• 例外が文書化されていても、満たされなかった不変条件が合格になるわけではありません。 意思決定のステータスと技術的な妥当性は、以下のセクションで示す別々の軸です。

発生頻度の軸では、引き続き「このメカニズムはどのくらいの頻度で作動するのか」を確認します。クエリ、ログの件数、テレメトリの読み取りなどで測定します。答えが一度もない場合は、潜在的としてコストを見積もります（発生頻度がゼロの場合と対処コストを比較します）。測定が不可能な場合は、発生頻度の軸にblindと記録し、評価項目はメカニズムと再現性の軸にもとづいて判断します。各項目には観測範囲と時刻を記録し、コードのメカニズム、デプロイ後の観測、前提を分けて扱います。task-pipelineのtemplates/finding-evidence.jsonが最小限のスキーマであり、収集ツールはmechanism／incidence／observed_scope／observed_atをサイドカーに書き込みます。不明点によって対応が変わる場合に限り、オペレーターに確認します。項目を記載するために、必ずしも聞き取りを行う必要はありません。

同じ考え方から、次の2つのルールが導かれます。

• 対策を提案する前に、それが影響する対象全体に照らして検証します。 資産クラスの解放を指示する項目が2件ありましたが、測定の結果、その資産クラスは意図的に保有されていた、製品独自の在庫であることがわかりました。
• 存在を生み出す経路をたどっていない限り、不在は証拠になりません。 販売がゼロである理由は、需要がないことまたは機能する経路がないことです。この2つに必要な対策は正反対です。

すでに決定されていることは指摘ではありませんが、何でもないわけでもありません

モジュールだけを読み、そのモジュールの使用箇所を読まない監査では、プロジェクトがすでに決定したことを欠陥として報告してしまいます。プロジェクト自身の言葉で書かれた決定であってもです。通常、その決定は指摘が引用するコードから数行のところに記されています。ある実行では、8 件中 5 件がそれに当たりました。

• 定義だけでなく、呼び出し箇所を読みます。 使用箇所を読まずに、モジュールに関する指摘を作成してはいけません。
• 各項目では、次の 3 つのどれに当たるかを明記します。 (a) 未決定、(b) ここに文書化された決定、(c) 別の場所で決定され、反映されていないもの。(a) と (c) は対応が必要です。また、まだ間違っている (b) も対応が必要です。決定状況と技術的妥当性は別の軸だからです。 文書化された決定でも、誤りや古い情報である可能性があり、外部との契約に違反することもあります。「仕様です」は正しさの証明にはなりません。そこで、(b) は次のように分かれます。
  • 受け入れられたトレードオフ — プロジェクトが意識的に受け入れた、実在し明確に特定されたコストを伴う制限（対応する契約のもとでの単一ブラウザー対応など）。欠陥ではなく、コストとともに 受け入れ済みの制限 として記録します。
  • 文書化された違反 — セキュリティ不変条件、外部との契約、または自身が掲げた目標に、依然として違反する決定（更新トークンのログ出力を許す ADR など）。これは引き続き finding として扱い、decision_id、見直す理由、反証となる根拠を記録します。監査が誤った (b)（誤検知）を記録するほうが、その項目を削除するより価値があります。一方、文書化された決定をすべて指摘から除外することは、偽陰性の体系的な原因となり、こちらのほうが見逃した場合のコストが高くなります。
• 判定が (c) の場合、対処は編集ではなく機械的なチェックです。 誰も検証しないルールが及ぶ範囲は、書かれた場所までです。5 件すべてで永続的な修正となったのは、見つかったコピーだけを修正するのではなく、プロジェクト自身の指示にすべてのコピーが従っているかを確認するガードでした。

3 つの判定と、3 つ目がある理由

clean・finding・blind。この語彙は固定されており、構築時に 4 つ目の値は拒否されます。

blind が設計のすべてです。 これがなければ、調査できなかったプローブと何も見つからなかったプローブは同じ空のセクションを出力し、読者は必ず後者の意味に受け取ります。これは、この手法における「沈黙は調査結果ではない」という考え方を、コマンドからプローブへと広げたものです。出力のない正常終了では、答えたことになりません。

ページでは、盲点の一覧を付録ではなく、独立したセクションとして表示します。 監査の盲点も、その結果の一部です。

バージョンチェックでは見つけられないクラス

同じバージョン文字列でも、ツリーは複数あります。 パッケージの各配布経路が提供するものは同じではありません。レジストリが提供するのはタグですが、プラグインマーケットプレイスとスキル用 CLI が提供するのはブランチの先端です。バージョンを上げずにブランチがタグより先に進むと、どの配布経路も同じ番号を返しながら、異なるコードを配布します。

2026-08-22 にこのファミリーで計測したところ、npm が提供したファイルは 4344 行、マーケットプレイスが提供した同じファイルは 4575 行でしたが、3 つの配布経路すべてが 1.15.0 と報告していました。ピンのチェッカーは終始問題なしでした。2 つの文字列を比較していたためであり、これは正しい動作です。

したがってラベルではなくツリーを比較し、実際に食い違い得る組み合わせを比較します。 このプローブの最初の草案では、レジストリの tarball とタグを比較していましたが、問題なしと報告されました。レジストリはタグから公開するため、両者が一致するのは当然です。常に問題なしを返す同語反復は、機構が自身の返答だけを根拠に信頼されるという、誤った成功の典型です。

さらに 2 つの落とし穴がありました。どちらも最初の草案に含まれており、現在はテスト用フィクスチャになっています。

• 一方の配布経路にのみ存在するパスは、乖離ではなくパッケージングの違いです。 tarball に含まれるのは files の許可リストで認められたファイルです。.github/ を不一致として数えた結果、1 ファイルが移動しただけなのに 22 件が検出されました。
• 両側が同じバージョンを主張している場合にのみ比較します。 ブランチがすでにタグより先のバージョンに上がっている場合、共通の主張はありません。その場合は clean ではなく blind です。

成果物 — サイドカーは常に、ページはリクエスト時のみ

docs/audit/<date>-audit.json は実行のたびに書き込まれます。HTML ページが書き込まれるのは --report を指定した場合のみです。 出力モードは 3 つあり、ブラウザーが必要なのはそのうち 1 つだけです。stdout（--stdout — ターミナルにサマリーを出力し、サイドカー以外は書き込みません）、json（サイドカーのみ。デフォルトです。機械が読み取り、ページもブラウザーも不要です）、html（--report — ページも生成します）。json のみ、または stdout の実行でブラウザーを開くことは決してなく、ブラウザーも不要です。ブラウザーが関係するのは --report のみです。

この分離は対称性のためではありません。スナップショットではなくラチェットとして機能させるのがサイドカーであり、次回の実行ではこれを読み込みます。これを省略すれば、以後のすべての実行が初回実行になったかのように、気付かないまま動作してしまいます。ページはレポートであり、レポートとは会話が終わった後も残る成果物です。誰も求めていないレポートは、誰も依頼しておらず、誰も保守しない文書です。それが docs/ 以下に未追跡のまま置かれ、git add -A ひとつでプロダクトの履歴に加わることになります。会話には会話で答え、ページが求められたときにページを書きましょう。

ページに含めるのは集計値と参照先だけで、本文そのものは決して含めません。 件数、上位クラス、傾向、自分のシステム内にある課題へのリンクです。スタックトレース、ログ行、データの行は含めません。レポートは人が転送するファイルです。共有できないレポートは、二度と作成されません。

シークレットは値ではなく、場所とクラスを報告します。 file:line、該当する認証情報の種類、そして対処法です。値はどちらの成果物にも stdout にも表示しません。監査が認証情報の漏えい先をもうひとつ増やしてはなりません。秘匿化は先頭部分だけではなく完全に行います。認証情報の半分とその前後の情報だけで、残りを特定できることが多いためです。

「読み取り専用」とはディスクではなく、対象についてのことです。 監査はプロジェクトのソース、データ、本番環境の証拠を読み取りますが、そのどれも変更せず、何もコミットしません。ただし、許可された出力ディレクトリ（デフォルトは docs/audit/。移動するには --out-dir を指定します）には、自身の成果物を書き込みます。サイドカーは常に書き込み、ページは --report の指定時に書き込みます。そこにサイドカーを書き込むことは読み取り専用への違反ではありません。対象のソースに書き込むこと、または何かを git add することが違反です。

スナップショットではなくラチェットとして機能させるのがサイドカーです。 各検出事項には、プローブとその場所から導出された ID が付与されるため、表現を変えても同じものとして追跡できます。次回の実行では、解消されたもの、新たに見つかったもの、3 回の監査を経ても残っているものが出力されます。最後の数値自体も検出事項です。誰も対処しない欠陥は、誰も記録に残さなかった判断です。

スクリプトが行うことと、あなたが行うこと

スクリプト	あなた
発見、レジストリ、機械的なプローブ、サイドカー、--report のページ、差分	境界をたどる調査、MCP の証拠、検出結果が何を意味するかの判断
4つ目の判定を拒否し、秘密情報を伏せ、自身の出力を除外すること	深刻度と作業量の判断、このプロジェクトに合った是正策を書くこと

この分担は、単なる整理ではありません。スクリプトに埋め込まれた判断は、誰も合意していないゲートになります。一方、説明文に残された機械的な作業は、誰も実行しない手順になります。このプロジェクト群では、どちらも実際に起きており、どちらも記録されています。

まずスクリプトを実行して、その盲点リストを読み、それからスクリプトが調べられなかった部分に時間を使ってください。

終了基準

監査の完了基準は、要求された成果物に応じて変わります（固定のページやブラウザーが必須ではありません）。

1. すべてのプローブに判定があり、blind のものにはすべて理由が記載されていること。
2. サイドカーが書き込まれていること（常に）。--report を指定した場合に限り、HTML ページも存在し、内部リンクが安全で正しく解決され、その検査／レンダリング状況（開いた、または --no-open を記録）が記載されていること。--report を指定しなければページは作成されず、それでも実行は完了です。
3. レポート内のすべての数値が、この実行で実行したコマンドによって得られたものであること。数を言い換えて記載することは、主張にあたります（evidence-docs）。
4. 少なくとも1つの数値を形の異なるコマンドで再導出し、その両方を出力していること。同じコマンドを再実行するのは、初回実行のスペルチェックにすぎません。
5. 提案する行がオペレーターに表示され、対象には何も書き込まれていないこと。

もっともらしい言い訳

言い訳	実態
「テストが通るから、プロジェクトは健全です」	テストが比較するのは、誰かが記録しようと考えた内容です。このフェーズ3が存在するのは、このプロジェクト群で最も深刻な欠陥が、影響を受けたどのリポジトリでも、テストスイートがすべて成功している状態では見えなかったためです。
「Sentry がないので、報告すべきエラーはありません」	それは同じ空のセクションを指しながら、事実としては正反対です。そのために blind があります。
「バージョンが一致しているので、各チャネルの内容も一致しています」	測定結果：3つのチャネル、1つのバージョン文字列、231行の差分。ツリーを比較してください。
「状況が分かるように、生ログの行を記録しておきます」	そうするとレポートを共有できず、再び作成されることもありません。集計し、参照先を示してください。
「認証情報を見つけました。実際に使えるか確認できるよう、貼り付けます」	レポートが2度目の漏えいになります。場所と種類を記載してください。是正策はローテーションです。
「その場にいるうちに、検出した問題を直せばいいだけです」	読みながら編集する監査では、自分自身を再実行して確認できません。次回の実行でも、修正と文言の変更を区別できなくなります。
「毎回同じ9項目を確認するので、発見の手順は省略できます」	そうすると、どんな入力に対しても同じ答えを返す計測器になります。それは計測器についての事実であって、プロジェクトについての事実ではありません。
「検出事項なし。問題ありません」	実行されたプローブで確認できる範囲に限ります。その言葉を口にする前に、盲点リストを読んでください。

起動条件

説明は短縮版です。1.98.0 まで含まれていた完全な起動条件リストを、ここにそのまま移してあります。このスキルは、引き続き次の条件で起動します。

「プロジェクト全体について、今現在実際にどうなっているか、何が完成し、何が未完成で、何が壊れ、何がまだ調べられていないのかを尋ねられたときに使用します。ゼロから調査します。プロジェクトが何であるかを発見し、それに基づいて選んだプローブのレジストリを実行し、本番環境の証拠（公開された成果物とソースの照合、CI の履歴、テレメトリーの有無）を読みます。その後、次回の監査で何が変わったかを確認できるよう JSON サイドカーを残し、リクエストがあれば自己完結型の HTML レポートも作成します。読み取り専用です。ボードに追加する行を提案しますが、何もコミットしません。起動条件 - 「プロジェクト監査」「プロジェクトを監査」「コードベース監査」「プロジェクトの状況」「未完了のものは何か」「プロジェクトのヘルスチェック」「аудит проекта」「проаудируй проект」「состояние проекта」「что не доделано」「аудит кодовой базы」。対象外：実行中の個別の成果物の監査（それはパイプライン独自の段階です）、差分のレビュー、スキルの構成確認。オプトアウトするには「без диагностики」と言ってください。」