running-ci-preflight

ci:preflight の実行

hogli ci:preflight は、厳選された一連のチェックを、ブランチが変更したファイルに限定して実行します — 各チェックは、master を落としてきた CI 障害クラスに対応付けられており、さらに常時有効なブランチ鮮度チェックも含まれます。これは hogli ci:insights（master で すでに 壊れているもの）に対する、プッシュ前のカウンターパートです。

pre-push フックは ci:preflight --strict を自動的に実行し、チェックが失敗するとプッシュをブロックします。 --no-verify で決してバイパスしないでください — 代わりに、報告された内容を修正してください。

ループ（フックがブロックしたとき、または完了を報告する前）

hogli ci:preflight --fix

1. --fix を付けて実行します — 安全な範囲でフォーマット、リント、自動修正を行います。
2. 各行を読みます: ✓ pass、✗ fail、⚠ warning（ブロックしない指摘）、→ advisory（自分で対応する）、· skipped（機能が存在しない）。
3. すべての ✗ fail を解消します — これらは --fix では対応できなかったものです（実際のリントエラー、壊れたロックファイル、マイグレーションの競合）。これらはプッシュをブロックします。
4. すべての → advisory に対応します — たとえば openapi の advisory → hogli build:openapi を実行してドリフトをコミットする、staleness の advisory → git merge origin/master。advisory は決してブロックしませんが、無視すると障害が CI に届きます。プッシュする前にこれらを解消してください。自分が持ち込んでいないドリフトも含みます — プッシュするブランチの状態は自分の責任です。
5. クリーンになるまで再実行し、その後プッシュします。

注意事項

• Strict = 失敗のみ。 --strict（フックが実行するもの）は ✗ fail の場合にのみ非ゼロで終了します。advisory はローカルでは検証できないクラスであるため、ブロックせずに警告を出します。クリーンな終了は「修正すべきものが何も残っていない」という意味であり、「CI が通る」という意味ではありません。CI が引き続き正式なゲートです。ブロックしないのは仕組み上の制約であり、スキップしてよいという許可ではありません。
• type-check は促しであり、実行ではありません。 CI に一致するのはリポジトリ全体の mypy 実行だけであり（mypy はインポートを辿るため、変更ファイルのサブセットでは逆依存関係の破損を見逃します）、それをコールドで実行すると数分かかります。毎回のプッシュに課すには負担が大きすぎます。そこで preflight はコマンドを実行せず、名前を示すだけにしています。あなたの変更が型に関するリスクがあるかどうかを判断し、自分で実行してください。CI は同じコマンドでブロックするため、ここでスキップした型エラーはフルの再実行として戻ってきます。
• complexity は警告のみです。 変更ファイル内の循環的複雑度が 10 を超えると ⚠ warning として表示され、決してブロックしません。CI も同じ警告を注釈として付け、CI レポートのコメントに投稿します。数値をごまかすのではなく、次にその関数に触れるときに簡素化してください。
• semgrep-devex はあなたのブランチが導入した検出事項について助言します。 変更ファイルとそのマージベースのコピーを 15 秒の予算内でスキャンします。どちらのスキャンも .github/workflows/ci-security.yaml で SEMGREP_IMAGE が固定するキャッシュ済みバージョンを使用し、ネットワークアクセスは無効化されています。ツールが見つからない場合はスキャンをスキップし、バックグラウンドでダウンロードを開始するため、次回の実行でスキャンされます。クラウドタスクや CI ジョブはそのダウンロードを開始しません。そこではネットワークアクセスを有効にして hogli ci:preflight --prepare-semgrep を実行してください。不完全なスキャンは理由を付けてスキップされます。master にすでにある検出事項は報告されません。CI は新しい検出事項でブロックするため、プッシュする前に修正してください。advisory はそのルールを表示するコマンドを出力します。
• snapshot-baselines は、frontend/snapshots.yml があなたのブランチで変更していないストーリーのエントリを失ったときに助言します。 これはマージコンフリクトの解決を誤ったときの症状です。ストーリーがまだレンダリングされる場合、マージキューはそのファイルを含むバッチを失敗させます。チェックが出力する git diff を実行し、削除するつもりのなかったエントリを復元してください。同じブランチで削除、名前変更、タイトル変更したストーリーのエントリは通ります。
• merge-queue-lane は警告のみで、pre-push フックはこれをスキップします。 いくつかの横断的なファイル（CI ワークフロー、レーンスクリプト）によって PR 全体がすべてのマージキューレーンを主張し、その結果キューがその PR の後ろで直列にマージされる場合に発火します。他の変更がそれらのファイルを必要としない場合は、それらを独自の PR に移動してください。
• Staleness はリスクベースです。 今 master をマージすると実際に何かが壊れる場合に発火します。つまり、テキスト上のマージコンフリクト（git merge-tree で計算、ワーキングツリーはそのまま）、両側で追加されたマイグレーション、両側で変更された生成ファイルの入力、または master で変更された CI ワークフローに加えて、behind/age のバックストップがあり、デフォルトでは積極的です（5 コミット / 2 日、環境変数 HOGLI_PREFLIGHT_STALE_COMMITS/HOGLI_PREFLIGHT_STALE_DAYS で調整可能）。これは最初は過剰に警告し、テレメトリから調整していくためです。発火したら master をマージしてください。助言のみで、自動マージは決してされません。
• · skipped (needs …) はベアチェックアウトやサンドボックスでは想定内です。needs stack/needs clickhouse は実行中の dev スタック（hogli start）を、needs node は pnpm install を、needs desktop-node は pnpm --dir products/desktop install を、needs agent-node は pnpm --dir packages/agent install を必要とし（どちらのネストされたワークスペースもルートのインストールから除外されており、独自のロックファイルを持ちます）、needs python-env は uv sync を必要とするため、同期されたプロジェクト環境が PATH 上の python になります。できるものは満たすか、残りは CI に任せてください。あなたの環境にフックがありません（node_modules がない）か？ プッシュする前に自分でループを実行してください。
• フラグ。 --against <ref> は明示的なベースと差分を取ります。--json は機械可読なサマリーを出力します。
• キルスイッチ。 HOGLI_PREFLIGHT_DISABLED=1 はコマンド（およびフック）を終了コード 0 の no-op にします。これはロールアウト/緊急用のレバーです。尊重してください。実行を強制するために unset しないでください。

なぜ重要か

ドラフトはすでに CI の一部を絞り込んで実行しています。無駄にコストがかかるのは、準備が整った PR が決定論的な問題でフルマトリクスに失敗し、修正されたうえでマトリクス全体を再実行するケースです。これをローカルで捕捉することが、最も低コストな CI の節約になります。