invigil

Invigil

インストールから初回の正常な使用までの経路を、人とエージェントのために検証します。

パッケージのインストールが正常に完了しても、最初に使うコマンドが失敗することがあります。Invigil は、リポジトリ品質チェックと、宣言された操作を実行して失敗の診断に必要な証拠を報告する Cold-Start Gate を組み合わせています。

開発中の新機能： ソースチェックアウトの外部で、公開前に特定の Python wheel を検証します。既存のスコアカード、公開済みアーティファクトのチェック、エージェントツールは引き続き利用できます。wheel の検証は未リリースです。pip install invigil と以下のリリース固定版には、まだ含まれていません。

初回使用デモを試す（ソースプレビュー）

Python 3.11 以降と venv をサポートする Linux で、ソースプレビューブランチを使用します。

git clone --branch feat/wheel-first-use-preview https://github.com/invigil/invigil.git
cd invigil
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python examples/first-use-demo/run.py

デモはオフラインで動作し、実際の wheel をチェックします。どちらもインストールできますが、一方は必須のデータファイルが欠けているため、初回使用コマンドが失敗します。そのファイルを追加すると、同じチェックが成功します。失敗内容を出力し、一時ディレクトリに JSON レポートを保存します。これは合成された例であり、上流プロジェクトの現行リリースについて主張するものではありません。

デモの詳細 · 独自の wheel を検証する · CI ワークフローテンプレート

プレビューでは、明示的なコマンドと、任意の期待出力が必要です。実行が成功すると、記録された環境でその操作が機能したことが確認できますが、リリース全般の安全性を保証するものではありません。見慣れないアーティファクトは、認証情報のない使い捨てワーカーで実行してください。Python の venv はセキュリティサンドボックスではありません。

invigilate — 試験を監督し、その規則を徹底すること。

---

Invigil がスタックで果たす役割

Invigil は既存のツールに取って代わるのではなく、それらではカバーできないプロダクト品質の課題に対応します。

機能	役割
リポジトリスコアカード	ドキュメント、設定、品質に関する規約をチェックし、修正を提案します
公開済みアーティファクト向け Cold-Start Gate	設定されたパッケージ／コンテナ操作と HTTP プローブを実行します
ローカル wheel の初回使用（未リリース）	候補アーティファクトを検証し、そのハッシュ、フェーズ、依存関係を記録します
既存のリンター、スキャナー、テスト	Invigil と併用して、引き続きコードの正確性とセキュリティをチェックします

クリーンインストール後のスモークテストスクリプトでも、同じパッケージングの不具合を検出できます。Invigil は、そのワークフローをより簡単に設定でき、プロジェクト間でレポートの一貫性を保てるようにすることを目指しています。

---

理由

スコアカードは、新規参入者やエージェントにとってプロジェクトが理解しやすいかを確認します。 失敗した静的チェックには、それぞれ推奨されるコマンドまたは編集内容が含まれます。実行レポートには失敗したステップと出力が保持されますが、すべてのアプリケーションの根本原因を推測できるわけではありません。

7 つのゲートでは、オンボーディング、エラー、成果物の検証、サプライチェーンの証拠、対象者向けドキュメント、コントリビューション、導入を扱います。評価は、リポジトリに実装されたチェックを要約するものであり、成果物が正常に実行されたことを証明するものではありません。実行の証拠には Cold-Start Gate を使用してください。

インストール

公開チャネル — 実行環境に合ったものを選んでください。

チャネル	適した環境	ワンライナー
PyPI	ローカル実行、Python に対応した CI	pip install invigil
GitHub Action	GitHub の PR	uses: invigil/invigil@v1
Docker (ghcr)	GitLab、Jenkins、その他の Python 以外の CI	docker run --rm -v "$PWD:/repo" ghcr.io/invigil/invigil score /repo
pre-commit	すべてのコミットでのオフラインチェック	hooks invigil-layout、invigil-secrets（下記）
MCP サーバー	エージェント（Claude Code、任意の MCP クライアント）	pip install "invigil[mcp]" → invigil mcp

すべてのリリースには、署名済みの成果物一式が含まれます。cosign 署名済みの wheel、sdist、コンテナイメージに加え、SPDX SBOM も含まれます。GitHub OIDC ID に対して cosign verify を実行して検証できます。

クイックスタート

これらのコマンドでは、公開済みのスコアカードを使用します。wheel の検証には、上記のソースプレビューを使用してください。

任意のリポジトリでローカル実行します。

pip install invigil
invigil score .            # human-readable scorecard + the exact fix for every failure
invigil score . --format markdown   # a PR-comment-ready table
invigil score . --format json       # machine-readable

CI にレポートのみを行うゲートとして追加します（スコアカードのコメントとバッジを投稿しますが、PR をブロックすることはありません）。

# .github/workflows/quality-gate.yml
name: Quality gate
on: [pull_request]
permissions: { contents: read, pull-requests: write }
jobs:
  invigil:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1        # v7.0.1
      - uses: invigil/invigil@7f31330715bb7e42f26032ce3e921fcf78d4acea        # v1.7.1
        with:
          enforce: "false"              # flip to true once the grade is stable

マージを目標ゲート未満でブロックする準備ができたら、enforce: "true" に切り替えるか（または .invigil.yml で project.enforce: true を設定してください）。

なぜ SHA なのですか？ invigil/invigil@v1 は動作し、最新の v1.x.y を追跡しますが、Invigil 独自の actions-sha-pinned チェック（G3）では、独自のタグも含め、固定されていないタグは失敗になります。SHA を固定し、Dependabot に固定値を更新させてください。末尾のコメントは、Dependabot が読み取る情報です。

この Action は、レポートと 2 つのバッジをステップ出力として公開します。スコアカードをジョブサマリーに渡し、shields.io からアクセスできる場所にバッジ JSON を公開できます。

      - uses: invigil/invigil@7f31330715bb7e42f26032ce3e921fcf78d4acea        # v1.7.1
        id: invigil
        with: { comment: "false" }
      - run: cat "${{ steps.invigil.outputs.report }}" >> "$GITHUB_STEP_SUMMARY"
      # outputs.badge → grade badge JSON · outputs.ai-badge → ai-ready badge JSON

仕組み

ドクトリンに対応する 2 つのレイヤーがあります。

• 静的ドクトリンスコアカード（すべての PR、数秒）— リポジトリのファイルシステムと GitHub のメタデータを検査します。LICENSE、README の長さ、.env.example、ディープヘルスエンドポイント、グローバルなエラー ID ハンドラー、SHA 固定されたアクション、強制されたロックファイル、カバレッジゲート、毎日公開される成果物のスモークテスト、5 件以上の good-first-issues、ドキュメントのインデックス、llms.txt／AGENTS.md などが対象です。テキスト／JSON／Markdown／shields.io バッジを出力します。
• Cold-Start Gate（毎晩、再利用可能 — invigil stranger）— クリーンなランナー上で、設定された公開済み成果物をインストールして起動し、宣言されたインターフェースを検査します。 新しいローカル wheel 経路では、セットアップ／インストール／初回使用を wheel ごとの単一の予算内に制限し、フェーズごとの結果を記録します。従来の経路はこれまでの動作を維持します。Web サービスには HTTP プローブを実行します。CLI イメージ（command: を持つ成果物）は最後まで実行され、終了コード 0 でなければなりません。リポジトリごとにコピーされていた 60 行の smoke-published.yml を、再利用可能な 1 つのワークフローに置き換えます。

# .github/workflows/stranger-gate.yml
name: Cold-start gate
on:
  schedule: [{ cron: "0 3 * * *" }]
  workflow_dispatch:
jobs:
  stranger:
    uses: invigil/invigil/.github/workflows/stranger-gate.yml@7f31330715bb7e42f26032ce3e921fcf78d4acea  # v1.7.1

PR による修正

任意の 修正ワークフローは、作業ブランチ上で機械的な修正を適用し、まとめて 1 つの PR を作成します。invigil score --fix --pr-mode を使用します。保護ブランチ向けの安全対策は維持されます。作業ブランチが削除されるまでは、その PR をマージせずにクローズした状態が尊重されます。設定と制限については、CLI リファレンスを参照してください。

設定

リポジトリのルートに .invigil.yml を配置します。静的スコアカードでは任意です（適切なデフォルトが適用されます）が、Cold-Start Gate では必須です（起動して検査する対象を宣言します）。完全なスキーマは schema/invigil.schema.json、例は examples/ を参照してください。

version: 1
project:
  name: my-app
  language: python
  min_gate: G4
  enforce: false
artifacts:
  - type: pypi
    name: "my-app[all]"
  - type: ghcr
    image: ghcr.io/me/my-app:latest
    port: 8000
probes:
  - { url: "/", expect_status: 200 }
  - { url: "/api/things", expect_json_count: { min: 5 } }
boot_budget_minutes: 10

軽量でモジュール式

開発者が回避するゲートは足かせになるため、Invigil は摩擦をゼロにするよう設計されています。

• コミット前に使える高速なオフライングループ — 各チェックには local／network／heavy のタグが付いています。 invigil check layout は、ネットワークを使わずにファイルシステムのチェックを約120msで実行します。

  # .pre-commit-config.yaml
  - repo: https://github.com/invigil/invigil
    rev: v1        # tracks the latest v1.x.y
    hooks: [{ id: invigil-layout }, { id: invigil-secrets }]
  

  負荷の高いネットワーク依存チェック（scorecard、Cold-Start Gate）は CI で実行します。 invigil score --offline／--layer local／--group supply-chain で、任意の方法に絞り込めます。

• フォークするのではなく、柔軟に対応します。 profile: strict | progressive | light、チェックごとの weights、ゲート判定はせず警告だけ出す optional、thresholds.fail_on を使って、独自の方針を設定できます。

• レジリエンスを前提に設計されています。 scorecard.dev がタイムアウトした場合は、評価から除外される SKIP になります。誤って A から C に格下げされることも、ビルドがクラッシュすることもありません。

  → 方針とゲートで、どちらについても詳しく説明しています。

ユーザーがエージェントの場合

読みやすさが求められる相手は、今や2種類です。リポジトリを初めて見る読者は、多くの場合 AI エージェントです。忍耐力の代わりにコンテキストウィンドウを持ち、直感の代わりに終了コードを使い、機械可読な形でリポジトリに記載された内容だけをもとに動作します。ai チェックグループは、llms.txt／AGENTS.md が存在するかどうかだけでなく、エージェントが実際にそれらを使って行動できるかを評価します。

チェック	エージェントへの約束
agents-md-actionable	AGENTS.md／CLAUDE.md に説明文ではなく、実行可能なフェンス付きコマンドが含まれています
llms-txt-shape	llms.txt が仕様に沿った形式で、10 KB のコンテキスト予算に収まっています
agent-context-fresh	エージェントへの指示が、説明対象のソースより90日以上古くなっていません
readme-heading-hierarchy	README が適切に分割されています（H1が1つ、適切なH2セクション）
exit-codes-documented	CLI の終了コードが列挙されています。エージェントは説明文ではなくコードに基づいて分岐します
llms-no-secrets	機械可読な情報に認証情報が漏れていません
agent-scope-visibility	エージェントのコードに使用ツールの一覧が宣言されています（影響範囲を把握するための前提条件）

ここから2つの成果物が生まれます。invigil score --format llm は、エージェントに読み取らせるために作られた、約1 KBの決定論的なレポートです。健全なリポジトリなら、必要なコンテキストは2行で済みます。もう1つは、独自の README に追加できる shields.io エンドポイントの ai-ready バッジです。

invigil score . --format ai-badge --output badges/ai-ready.json   # commit this

![AI-ready](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/badges/ai-ready.json)

CI では Action が自動で出力します。steps.<id>.outputs.ai-badge に同じ JSON へのパスが設定されます。

MCP サーバー

エージェントがシェルコマンドを実行する必要はありません。Invigil は MCP にネイティブ対応しています（mcp-name: io.github.invigil/invigil）。

pip install "invigil[mcp]"    # optional extra; the core CLI stays zero-dep
invigil mcp                   # stdio server

// e.g. .mcp.json for Claude Code — any MCP client works
{ "mcpServers": { "invigil": { "command": "uvx", "args": ["--from", "invigil[mcp]", "invigil", "mcp"] } } }

読み取り専用ツールは3つです。evaluate_repo（スコアカード。形式は llm または json）、check_group（高速なオフライングループを1つ実行）、preview_fixes（--fix が適用する変更計画。エージェントは独自の編集ツールで変更を適用するため、ここでは何も書き込みません）。

方針

苦情がないからといって、問題がないとは限りません。沈黙こそ、プロジェクトが受け取る最も強い否定的なシグナルです。 これが Silent User Doctrine であり、Invigil はそれを適用します：ゲートの意味と調整方法。

安定性

Invigil は Alpha です。Alpha が意味する内容は docs/stability.md に明記されています。CLI、終了コード、JSON の形式、バッジ JSON、MCP ツールは自動化に使える程度に安定していますが、個々のチェック結果は安定していません。また、すべてのレポートには doctrine_version が含まれるため、リポジトリが後退したのか、評価基準が変わったのかを見分けられます。

貢献

Issue や PR を歓迎します。CONTRIBUTING.md と 初めての方におすすめの Issueをご覧ください。Invigil は CI で自身を評価しますが、現在、自己評価の結果はレポートにのみ表示されます。範囲を絞った 初心者向けタスクやベンチマークタスクもご覧ください。

ライセンス

Apache-2.0 — LICENSEをご覧ください。