Veripsa Core の仕組み

よく聞かれる 6 つの質問への短い答えと、該当セクションへのリンクです。詳細はそれぞれのセクションをご覧ください。

• 自分のリポを理解できる？ — 公開連携仕様を正典とする対応言語・ファイル形式マトリクスを参照。
• 自分の PR にチェックはどう見える？ — 4 つのアドバイザリー判定（Clear / Heads up / Wait in line / Unknown）。
• マージはブロックされる？ — GitHub プランごとの branch protection との関係。
• インストール手順は？ — ホスト型 GitHub App、CI 変更は不要。
• Wait in line の対応は？ — スナップショットを確認する。任意の veripsa-ack ラベルで意図的な override を記録できる。
• 「Unknown」とは？ — 「わからない」を正直に返す状態。よくある原因あり。

GitHub から Veripsa Core をインストールします。ホスト型の GitHub App として動くので、エージェントのセットアップも、CI に追加するものもありません。

Veripsa Core

Veripsa Core を初めて使う場合は、はじめ方ガイドを読む に、PR チェック、Wait in line への対応、branch protection の選択肢をまとめています。

インストール時に Veripsa Core がアクセスできるリポジトリを選びます。各リポジトリ内の pull request を相互に調整しますが、別々のリポジトリをまたいだ調整は行いません。カバー対象のリポジトリは、GitHub からいつでも変更・アンインストールできます。

通常どおり pull request を開いてください。Veripsa Core は各 PR にチェックを投稿し、他の PR の作成・変更・マージに応じて更新します。使うのは PR に紐づく必要最小限の運用メタデータだけです。ソースファイル本文は保存・表示・コードレビュー用途に利用しません。

チェックは次の 4 つの状態のいずれかを返します。これらはアドバイザリー (助言) です — Veripsa Core が観測した内容を伝えるもので、必ず従わなければならない指示ではありません。

• Clear. Veripsa Core から見えている他の open PR との衝突は見つかりませんでした。
• Heads up. この PR は別の open PR と衝突する可能性があり、きれいにマージするには一部の作業が必要かもしれません。
• Wait in line. 強い衝突リスクが見えているため、重なっている作業の後ろに安全な順序で待つほうがよい状態です。これは助言であり、単独でハードブロックすることはありません — マージのゲートになるかどうかは branch protection の設定が決めます。
• Unknown. Veripsa Core では判定できません。対応範囲外の変更や、リポジトリ文脈がまだ利用可能になっていない場合などに表示されます。Unknown は正直な「分からない」のサインであり、衝突がないことの保証ではありません。

material な衝突（Wait in line、または進行中の相手 PR を名指しする Heads up）はチェックタイトル「Veripsa — Paused (acknowledge to proceed)」として表示され、GitHub の action_required conclusion を使います。Veripsa 自体が定例の acknowledgement 作業を追加するわけではなく、リポジトリ側で Veripsa check を required にした場合だけマージのゲートになります。具体的な重なりを確認したうえで、監査可能な例外を記録して check を neutral にしたい場合は、任意で veripsa-ack を付けられます。PR ごとの定例操作や承認 (approval) ではありません。あとから重なっている作業が変わった場合、Veripsa Core は再びその衝突を可視化できます。

対応言語・フレームワーク・構造面のカバーマトリクスは、公開連携仕様を正典とします。代表的な範囲には Python、TypeScript、JavaScript、Go、Java、Rust、Astro、Vue、Svelte、CSS、Sass、Less、Stylus、スキーマ、API、IaC、設定ファイルが含まれ、完全版は公開マトリクスを正典とします。現在の範囲外の作業では、推測せず正直な Unknown を返すことがあります。文書化したメタデータを作るためにソースファイル本文を処理時に一時的に読むことがありますが、本文は保持・表示しません。

対応言語・ファイル形式の正典を開く。

対象外: 生成ファイル、バイナリ資産、ベンダーバンドル、現在のカバー範囲外のファイル。対象外のファイルだけを触る pull request では Unknown が返ることがありますが、これはバグではなく意図された動作です。

Unknown は意図的な状態です — 裏付けのない判定を出すよりも、Veripsa Core は「分からない」と言うことを選びます。次のような変更で表示されることがあります。

• PR の大部分が、現在の対応範囲の外にある。
• PR が、Veripsa Core では助言型の判定を出せないファイルに触れている。
• インストール直後、大きなリポジトリ変更のあと、または長く動いていなかったため再解析が必要なときに、リポジトリまたはブランチの文脈がまだ利用可能になっていない。
• 推測するより、人間のレビューに委ねるほうが安全な状態である。

対処方法: ほとんどの場合、特別な対応は不要です。Unknown は「解析していない、安全とは言っていない」という意味です — 通常どおりに PR をレビューしてください。Veripsa Core が理解できるはずだと考えていた作業で Unknown が繰り返し出る場合は、リポジトリ名と PR URL を添えてサポートに連絡してください。

Veripsa Core は各リポジトリの中で pull request を調整します。モノレポでも、カバー対象の範囲では open PR を同じリポジトリ内の作業として扱います。

現在、Veripsa Core は同じ GitHub アカウントが所有していても、リポジトリをまたいだ調整は行いません。リポ A の PR とリポ B の PR は、同じプロダクト領域の作業であっても、お互いに重なりについて警告し合うことはありません。リポジトリ間の調整は将来のロードマップに含まれており、現時点での提供範囲ではありません。

Veripsa Core は常にアドバイザリーです — pull request ページでチェックの状態を確認できる機能は、Free を含むすべての GitHub プランで利用できます。そのチェックをゲート (マージ前に必ず通す必要のある required check の 1 つ) に変えるには GitHub の branch protection が必要で、private リポジトリでの利用可否はプランによって異なります。

Veripsa Core を required にするかどうかはあなたの判断です — 後述の「運用のベストプラクティス」を参照してください。required にするかどうかに関わらず、アドバイザリーのシグナルとして役立ちます。

Veripsa Core は「正確に黙る」ことを目指しています — 警告を出すときは、読む価値がある状態を目標にしています。それでも、人間のトリアージが必要な広いパターンはいくつかあります。

• 広く共有される面. リポジトリ全体で共有されるファイルや領域は、独立した作業を実際より関連して見せることがあります。2 つの PR が本当に独立している場合は、通常の助言型マージ手順を続けられます。通常利用に acknowledgement は不要で、material warning の意図的な例外を記録したいチームだけ任意の ACK ラベルを使えます。
• 新規ファイルのみ. 両方の PR が、まだ main に存在しないファイルを追加している場合、それらのパスについては片方がマージされて main に取り込まれるまで、Veripsa Core は Clear ではなく Unknown と返すことがあります。これはバグではなく正直な返答です — まだ比較対象がありません。
• 任意の ACK ラベル. veripsa-ack ラベルは「この時点の warning を確認したうえで、マージすると決めた」という意味です。material warning は action_required として投稿され、ラベルを付けると reviewed exception が記録されて check は neutral になります。承認 (approval)、レビューのサインオフ、衝突が解決したという主張ではありません。重なっている作業が変わると ACK は current ではなくなり、material warning が戻ることがあります。
• アカウント越え / 転送されたリポジトリ. リポが GitHub アカウントをまたいで転送された場合、以前のオーナーの下にあった履歴は引き継がれません (プライバシー境界)。Veripsa Core は新しいオーナーから見た main を起点に再取り込みします。

Veripsa Core は、アドバイザリーチェックを動かすために必要な GitHub App 権限とイベントだけを使います。イベントは必要最小限の content-free なリポジトリ / pull-request metadata として処理されます。ソースファイル本文はその metadata を作るため一時的に読み取ることがありますが、保持・表示しません。

Veripsa Core は GitHub App first で、早期アクセス中は無料です。GitHub Marketplace を掲載と将来の課金導線にします。旧来の direct billing は現在のプロダクトフローには含めず、今のインストール導線に checkout ステップはありません。

Veripsa Core は、既存のレビュープロセス — マージキューを含む — の隣に並べて動かすように設計されています (詳しくは「マージキューと併用する Veripsa Core（英語）」を参照)。設定時に見る短いチェックリストです。

• アドバイザリーから始める. 実際のリポにインストールし、チェックを required にせずに、数週間かけてチームに判定を見てもらいます。マージのゲートに使う前に、シグナルの性質を理解できます。
• required は十分に見てから. 自分のリポジトリで複数の判定を確認してから、GitHub ruleset または branch protection の required check リストに Veripsa Core を追加できます (private リポでは GitHub 自体のプランが対応している必要があります)。任意の veripsa-ack ラベルは、Wait in line を越えてマージする意図的な override を監査可能な形で記録できます。
• 4 つの判定を額面どおりに読む. Clear = 進行中の PR と重なるものがない。Heads up = マージ前に確認したほうがよい。Wait in line = 強い衝突リスクあり。待つか、通常の助言型マージ手順を使う。Unknown = 解析していない、安全とは言っていない。通常どおりレビュー。
• パーセンテージはプランのカバー上限使用率として読む. ダッシュボードに表示するのは、現在のプランのカバー上限使用率です。分母はリポジトリ全体ではなく、プランのカバー上限です。
• 複数の連携先は別々のスコープとして扱う. 複数のスコープを連携している場合、ダッシュボードは最も注意が必要なスコープを表示します。上限超過、上限接近、使用率が最も高いものの順で選び、件数を合算した架空の組織全体パーセンテージにはしません。

Veripsa Core はアドバイザリーであり、単独でマージをハードブロックすることはありません。そのチェックがマージをブロックできるかどうかは、完全にあなた次第です: マージを止めるかどうかは GitHub の branch protection のルールが決めます。既定では、Veripsa Core はあなたの判断を補助するだけで、判断そのものを代わりに下しません。

Veripsa Core は GitHub の設定からいつでもアンインストールできます。アンインストールすると処理が停止し、GitHub インストールの再構築可能なコンテンツフリー作業セットがパージされます。ただし account erasure request と同じではありません。保持された advisory history と lifecycle record の削除には別途 erasure process が必要です。詳細は プライバシーポリシーをご確認ください。

リファレンス資料は GitHub の GetVeripsa 組織の公開リポジトリにあります（アカウント不要で読めます）。Core エンジン本体は引き続き private です。

• veripsa-webhook-spec — GitHub event、出力、ACK、データ取り扱いの公開契約。private な判定エンジンは含みません。
• ai-pr-collision-lab — 2 つの準備済み pull request でチェックを確認するための小さなデモ。