ADR-27 — ツール配布・インストールモデル

ステータス: Accepted、2026-05-22;部分実装。

エンドユーザーへのRigorの配布・インストール方法を記録する。中心的な原則 — RigorをターゲットプロジェクトのGemfileに追加しない — は批准済みであり、それが依拠する最新Ruby専用の立場（WD7）も同様。チャンネル推奨事項は以下のとおり：ランタイムバージョンマネージャー（mise / asdf）が最前線のパス、コピー＆ペーストできるスタンドアロンCIワークフローテンプレートがCIパス（Nixは代替であってヘッドラインではない）、コンテナイメージと自己完結型シングルバイナリが二次的・将来的なオプション。ここまでに出荷: Nix flakeのpackages / apps出力、公開されたコンテナイメージ（Dockerfile + .github/workflows/container.yml）、そしてGemfileエントリーを非推奨にする機械可読インストールガイド（docs/install.md、v0.1.14）。なお保留:コピー＆ペーストできるスタンドアロンCIワークフローテンプレートと、自己完結型シングルバイナリ。

コンテキスト

Rigorはrigorという実行ファイルを持つrigortype gemとして配布されている（RubyGemsにrigorがすでに存在するため、gem名はrigortypeとなっている）。READMEの「Installation」セクションは現在、group :development配下のgem "rigortype"をターゲットプロジェクトのGemfileに追加することを推奨しており、一回限りの代替手段としてgem install rigortypeを挙げている。

このgemには、Gemfileパスが実害を及ぼす2つの特性がある：

1. required_ruby_version = [">= 4.0.0", "< 4.1"]。RigorのコードベースはRuby 4.0をターゲットにしている — flake.nix / .ruby-versionでピン留めされた開発用Ruby（AGENTS.md参照）。現時点でRuby 4.0上で動作している本番Rubyアプリケーションはほぼ存在しない。この制約を持つGemfileエントリーは、解析対象プロジェクト全体をRuby 4.0に縛りつける — これはRigorが対象とするユーザー層にとって受け入れがたい。

2. 3つのランタイム依存関係（prism、rbs、language_server-protocol）。Rubyのピン設定を脇に置いたとしても、これらをターゲットプロジェクト固有の制約に対して解決しようとすると、SteepやヘビーなリンターをアプリケーションのGemfileに追加する際のよく知られた問題が再現される — 共有gemのバージョン衝突（特にrbs）と、ランタイムにRigorを必要としないアプリケーションの依存関係グラフへの汚染。

Rigorはライブラリではなくツールである。コンパイラやリンターと同様に、プロジェクトを解析するがそのランタイムの一部ではない。正しいメンタルモデルは「プロジェクトのdevelopment依存関係」ではなく「自身のRubyを持ち、プロジェクトに向けて実行するツール」である。Rigorはターゲットプロジェクトをデータとして読み取る — Gemfile.lockをパースし、vendor/bundleのsig/ディレクトリを走査し、rbs_collection.lock.yaml（ADR-25）を読み込む — が、プロジェクトのgemを自身のRubyプロセスに読み込むことは決してない。解析にRigorがプロジェクトのバンドルを共有する必要はなく、個別にインストールしても何も失われない。

Rubyエコシステムには、この状況に対するまったく同じ先例がすでに存在する。solargraphは慣例的にアプリケーションのGemfileから除外されている；ruby-lsp（Shopify）はGemfileへのエントリーを明示的に非推奨とし、代わりに別の「composed bundle」をブートストラップすることで、言語サーバーの依存関係ツリーをプロジェクトのものから切り離している。Rigorも同じ制約に直面しているが、Ruby 4.0のハードピンにより制約はより厳しい。

Rigorは意図的に最新Rubyのみをターゲットにしており、このADRはそれを前提ではなく決定として記録する（WD7）。Ruby 4.0のピンは拡張して広げるべき偶発的なものではない：Rigorが構築されているruby/rbsは最新Rubyを追跡しており、RigorはRactorとその他の最新ランタイム機能に依存している（ADR-15）。Ruby 3.3 / 3.4のサポートは検討の上で却下された代替案である。以下の配布モデルはその決定の結果である：Rigorが解析対象プロジェクトの多くが実行していないRubyにコミットしているため、自身のRubyと共に配布されなければならない。ツールはホストプロジェクトのランタイムを指定すべきでない。

決定

RigorはターゲットプロジェクトのGemfileにインストールしない。READMEとすべてのオンボーディング資料はgroup :developmentエントリーの推奨をやめる。推奨されるすべてのチャンネルは、Rigorをターゲットプロジェクトのバンドルから隔離した状態でインストールするため、RigorのRubyと3つの依存関係が解析対象プロジェクトの解決に入り込むことはない。

推奨チャンネル（優先順）：

1. 最前線 — ランタイムバージョンマネージャー（mise、asdf）。ヘッドライン推奨。バージョンマネージャーはRuby 4.0と固定されたrigortypeバージョンの両方をプロジェクトごとにプロビジョニングし、Gemfileへの汚染なし（WD2）。

2. CI — スタンドアロンワークフローテンプレート。コピー＆ペーストできる.github/workflows/rigor.ymlで、Rigorを独立したジョブで実行する（Ruby 4.0用ruby/setup-ruby、インストール、rigor check）。Nixはハーメチックなための代替CIパスとして提供される（WD3）。

3. 二次的 — コンテナイメージ。Ruby 4.0を組み込んだ公開OCIイメージ。CIとNixが不要なゼロRuby環境向け（WD4）。

4. 将来的 — 自己完結型シングルバイナリ。Ruby plus gemをバンドルした単一の実行ファイル。配布が「1ファイルをダウンロード」になる。tebakoが明白なツール；軽量なホームグロウンパッケージングもスパイクに値する。未確定（WD5）。

5. 継続 — グローバルなgem install rigortype。PATH上にRuby 4.0を持つユーザーへのシンプルなパスとして文書化を維持するが、ヘッドラインではなくなる（WD6）。

Nix（packages / apps flakeアウトプット）は、すでにNixを実行しているユーザーとCIのための代替として維持される。ハーメチックなクロージャを必要とする場合のヘッドラインチャンネルではない（WD3）。

作業決定

WD1 — Rigorはプロジェクトのgemfile依存関係ではない

group :developmentのgem "rigortype"推奨はREADMEとすべてのオンボーディングSKILLから削除される。理由は§コンテキストにある：Ruby 4.0のピンはホストプロジェクトのランタイムを汚染し、3つのランタイム依存関係はその解決を汚染する。これはADRの残りが構築される基盤となる決定である。

スタンドアロンではあるが依然としてGemfileベースの代替案 — Rigorが自身の隔離されたバンドルをブートストラップする（.rigor/Gemfile、ruby-lspの「composed bundle」パターン） — は検討された。これは解決の汚染をきれいに解決するが、インタプリタのプロビジョニングは解決しない：ユーザーはまだRuby 4.0を利用可能にしておく必要がある。バージョンマネージャー（WD2）は両方を一度に解決するため、隔離バンドルブートストラップは個別のメカニズムとして追求されない。このパターンはbundle exec rigorの呼び出し形式にこだわるユーザーへの有効なフォールバックとして残り、そのように文書化される場合もあるが、推奨チャンネルではない。

WD2 — ランタイムバージョンマネージャーが最前線チャンネル

mise（および同じモデルのasdf）がヘッドライン推奨である。これはRubyプロジェクト向けにユーザーがすでに持っているツール1つで、問題の両方の側面を解決する唯一のチャンネルだからである：

• インタプリタのプロビジョニング — miseはRuby 4.0自体をインストールするため、「ユーザーがすでにRuby 4.0を持っていなければならない」という前提条件がなくなる。
• プロジェクトごとのバージョンピン留め — mise.toml / .tool-versionsはリポジトリにコミットされ、ローカルとCIの間で再現可能な形で、rigortypeバージョンをRubyバージョンの隣にピン留めする。Gemfileへの関与は不要。

miseはRubyプロジェクトのコミュニティ標準ランタイム/ツールマネージャーになる明確な軌跡をたどっており、最も人間工学的かつ最も将来に沿った最前線チャンネルとなっている。asdfは同じモデルを共有しており、それを使用するユーザー向けの同等品として文書化される。

gemはバージョンマネージャーが管理するRubyにインストールされ（gemバックエンド）、実行ファイルrigorはその環境内でPATH上に置かれる。PATH上のrigorはエディタとの親和性も高い — エディタはstdio経由でrigor lspを起動し（ADR-19）、プレーンなPATHルックアップはすべてのエディタ統合が依存できる最もシンプルなものである。

WD3 — CIはスタンドアロンワークフローテンプレート、隔離ジョブで実行

CIチャンネルはsetup-rigor GitHub Actionではなく、コピー＆ペーストできるスタンドアロンワークフローテンプレート（.github/workflows/rigor.yml）である。

ジョブの隔離は必須である。Rigorは独自のジョブで実行される — 独自のランナー、クリーンな環境。これはスタイルの好みではなく、実際の競合に対する修正である。ruby/setup-rubyはそのジョブのアクティブなRubyを設定するため、プロジェクトのテスト用Ruby（多くの場合3.2 / 3.3 / 3.4マトリクス）をプロビジョニングするジョブは、RigorのRuby 4.0を同時にプロビジョニングできない — 2番目のsetup-ruby呼び出しが最初のものを上書きしてしまう。独立したジョブ — さらには独立したワークフローファイル（独立したトリガー、コンカレンシー、ステータスバッジのため） — はRigorにRuby 4.0のプロビジョニングが他と競合しないクリーンな環境を与える。解析器をテストワークフローから切り離すことはそれ自体として良い実践でもある。

アクションではなくテンプレート。隔離されたジョブの内部では、ワークフローは約8行の透明な内容に収まる：actions/checkout、ruby/setup-ruby（ruby-version: "4.0"）、Rigorのインストール、rigor check。これらの行をラップするコンポジットsetup-rigorアクションは、保守が必要なアーティファクト — マーケットプレイス上の存在、アクションのバージョン管理、リリースプロセス — を追加するが、得られる価値は薄い；実際の唯一のメリットは4.0の詳細を隠すことでユーザーがプロジェクトのRubyに合わせて誤編集できなくなることである。テンプレートは透明で、サードパーティアクションのレビューが不要で、ペーストで機能する。setup-rigorアクションは需要に応じて延期されており、v1の成果物ではない；シングルバイナリ（WD5）が実現すれば、その価値の計算式が変わる可能性がある。

バージョンのピン留めと更新。Dependabotはrun:ステップ内のgem install rigortype -v Xの呼び出しを認識しない — BundlerエコシステムとしてGemfile / gemspecを追跡し（bundlerエコシステム）、GitHub Actionsエコシステムとしてuses:のアクションRefを追跡するが、任意のシェルスクリプトは対象外。そのためテンプレートは2つのピン留め形式を提供する：

• デフォルト — CI専用の隔離されたGemfile。2行の.github/rigor/Gemfile（gem "rigortype", "~> 0.1"）とコミット済みロックファイル。RigorジョブのみがBUNDLE_GEMFILE経由で使用する。Dependabotのbundlerエントリーをdirectory: /.github/rigorのスコープで設定すれば、RigorのアップデートをautoでPRできる。ロックファイルは3つの推移的依存関係をピン留めして完全な再現性を確保する。これはWD1が有効なフォールバックとして記録した隔離バンドルパターン — ここではCIスコープで非ルートのため、アプリケーションの解決に入り込まず、そのRubyを制約しない。ruby/setup-rubyのbundler-cache: trueでキャッシュできる。
• 最小構成 — ピン留めされたgem install。gem install rigortype -v "X.Y.Z"。ファイルを2つコミットしたくないユーザー向け；完全に可視だが、更新は手動（Dependabot非対応）。

Nixは、CIでNixをすでに実行しているチームのためにハーメチックなクロージャが欲しい場合の文書化された代替CIパスとして維持される（スライス2のflake packages / appsアウトプットを消費する）。CIチャンネルをNixとCachixバイナリキャッシュの上に構築すること — nix-emacs-ciをモデルにした — は主要なメカニズムとして検討され却下された：nix-emacs-ciが事前ビルドされたバイナリレイヤー（キャッシュ）を構築するのは、CIに事前ビルドされたEmacsがないからだが、Rubyにはすでにruby/setup-rubyにそのレイヤーが存在するため、Nixルートは問題に対して重すぎる仕組みとなる。

出荷前に検証すべき注意点がある（スライス3）：テンプレートの速度はruby/setup-rubyがランナーイメージ向けに事前ビルドされたRuby 4.0を公開しているかどうかに依存する。事前ビルドされた4.0がまだ利用できない場合、setup-rubyはソースからコンパイルする — 利用可能になるまで実行ごとに数分かかる。構造的なものではなく、一時的なタイミングリスク（Ruby 4.0は最近のもの）；Nixとキャッシュの代替手段はその期間に速いCIを必要とするチームの橋渡しとなる。

WD4 — コンテナイメージは二次的なCI / ゼロRubyチャンネル

公開OCIイメージ（エントリーポイントがrigor check、プロジェクトはバインドマウント）はNixを必要としないCIとゼロRuby環境に提供される。Ruby 4.0はイメージに組み込まれており、ホストはコンテナランタイムのみを必要とする。

ローカル開発とエディタ統合の人間工学が劣るため、二次的であり最前線ではない：バインドマウントのUID/パーミッション問題、遅いフィードバックループ、コンテナ経由のstdio経由rigor lspはエディタにとって扱いにくい。イメージはCI / バッチの利便性であり、開発環境ではない。

WD5 — 自己完結型シングルバイナリが将来の理想

長期的な理想はRuby plus gemをバンドルした単一の自己完結型実行ファイルである — 配布は「1ファイルをダウンロードして実行する」に集約され、GoやRustのツールが享受するモデルになり、他のすべてのチャンネルの摩擦が消える。

tebakoが明白な既存ツールである。Ruby 4.0のサポートとビルドの複雑さは未検証であり、シングルバイナリのリリースはプラットフォームごとのビルドマトリクスを意味する（flakeはすでに4つの{aarch64,x86_64}-{darwin,linux}システムをターゲットにしている）。tebakoにコミットする前に、軽量なホームグロウンパッケージングが明示的にスパイクに値する — 例えばリロータブルなRubyとgemをランチャースクリプト付きtarballとして配布する方法、またはAppImage / squashfsstyleバンドル。これは本物のエンジニアリングプロジェクトであり、パッケージングの微調整ではない；マイルストーンなしでキューに積まれており未確定。

WD6 — グローバルなgem installは維持されるが優先度は下がる

gem install rigortypeはPATH上にRuby 4.0を持つユーザー向けの最もシンプルなパスとして文書化を維持する。その対象ユーザーにとって誠実で有用だが、ヘッドラインではなくなる：プロジェクトごとのバージョンピン留めを提供しない（ローカル/CI間のドリフト）し、ユーザーの多くが持っていないRuby 4.0をまだ前提とする。すべてのオンボーディング資料でバージョンマネージャーチャンネルの下に位置づけられる。

WD7 — Rigorは最新Rubyのみに留まる；3.3 / 3.4のサポートは却下

Rigorのrequired_ruby_versionは>= 4.0, < 4.1のまま維持される。フロアをRuby 3.3 / 3.4をカバーするまで下げること — 解析対象プロジェクトの多くが実際に実行しているバージョン — は検討の上で却下された代替案である：

• ruby/rbsは最新Rubyを追跡する。RigorはRbsの上に構築されており、rbsに従うことはrbsがターゲットとするRubyに従うことを意味する。
• Ractorとその他の最新ランタイム機能。Rigorのコンカレンシー方向性（ADR-15）とエンジン作業は最新ランタイムに依存する。フロアを広げると、それらを諦めるかエンジン全体で互換性シムを強制することになる。
• フロアを広げるコストはすべてのコントリビューション（新しい構文/APIの回避）において支払われ、エンジンを制約する；メリット — ユーザーがプロジェクトのRubyに対してRigorを実行できるようにすること — は代わりにこのADRの配布モデルによって提供され、どのみちRigorをプロジェクトのRubyとは無関係に自身のRubyで実行できるようにする。

この決定はADRの残りが依拠する前提である（§コンテキスト参照）。rbsまたはランタイム機能の計算式が変わった場合は再検討される可能性があるが、機会主義的にピンを広げることで再検討されるものではない。

WD8 — ホストOSにインストールする；開発コンテナの内部ではない

開発コンテナ（VS Code devcontainers、Dockerベースの開発環境）内で作業する開発者はRigorをそのコンテナ内にインストールすることができるが、Windows以外のホストでの推奨配置はホストOSであり、バージョンマネージャー（WD2）と共に置くことになる。コンテナ内で解析器を実行すると、ホストエディタ / ファイルとの間のファイルシステムおよびプロセス境界を越える検査オーバーヘッドが増加する。Windowsでは、信頼性の高いホストOS Ruby 4.0がより弱い選択肢であり、コンテナ内にRigorをインストールすることが推奨パスとなる。

これはWD4とは独立している：WD4はCIチャンネルとしてのRigor独自の公開イメージであり；WD8は開発者自身がコンテナ内で開発する際にRigorを置く場所についてである。

結果

ポジティブ

• RigorがホストプロジェクトのRubyバージョンを指定しなくなる。Ruby 4.0のピンはRigor固有の問題となり、すべての解析対象プロジェクトに課せられる制約ではなくなる。
• 依存関係グラフへの汚染なし。prism / rbs / language_server-protocolがターゲットプロジェクトの解決に入り込まない；GemfileにSteepを追加する類の衝突が発生しない。
• Gemfileを関与させないプロジェクトごとの再現性。バージョンマネージャーチャンネルはRuby 4.0とrigortypeバージョンをmise.toml / .tool-versionsにコミットし、再現可能にピン留めする。
• CIは透明でコピー＆ペーストできるワークフロー。独自ジョブでRigorを実行するスタンドアロンの.github/workflows/rigor.ymlは、どのRuby CIメンテナーにとっても読みやすい — サードパーティアクションなし、採用・運用すべきNixやCachixなし。
• エディタ統合がシンプル。推奨されるすべてのチャンネルでrigorがPATH上に置かれ、エディタがrigor lspを起動するために必要なのはそれだけ（ADR-19）。

ネガティブ

• 文書化・維持すべきチャンネルが増える。READMEとSKILLは1行のGemfileエントリーではなくチャンネルマトリクスを説明しなければならない。Nix代替案は依然としてgemset.nix / buildRubyGemのメンテナンス負担を追加する（Nixがヘッドラインではなく代替手段になったため、バイナリキャッシュは必要なくなった）。
• おなじみのRubyオンランプが削除される。「Gemfileに追加する」はRuby開発者が期待するものである；WD1はその期待を意図的に破る。オンボーディングドキュメントはなぜそうするのかを前もって説明しなければならず、省略のように読まれないようにする必要がある。
• 単一の推奨チャンネルがない。ローカル開発、CI、ゼロRuby環境は異なるチャンネルに誘導される。明確な優先順位と決定テーブルをドキュメントに設けることで緩和される。

持ち越し

• シングルバイナリチャンネル（WD5）は未解決 — Ruby 4.0におけるtebakoの実現可能性対ホームグロウンパッケージングは未調査のスパイク。
• CIテンプレートのタイミングリスク（WD3） — ruby/setup-rubyが事前ビルドされたRuby 4.0を公開しているかどうか — はスライス3で検証が必要。
• setup-rigorコンポジットアクションは延期（WD3）；需要に応じて再検討、またはシングルバイナリ（WD5）の実現で価値の計算式が変わった場合。

実装スライス（提案）

このADRではスライスは予定されていない。

スライス1 — ドキュメント：Gemfileエントリーの非推奨化

• README「Installation」セクションの書き直し：バージョンマネージャーチャンネルを先頭に、チャンネルマトリクス / 決定テーブルを提示し、gem installを降格させ、group :developmentの推奨を削除する。
• 専用のdocs/installation.mdがフルマトリクスの候補ホームとなる；docs/manual/09-editor-integration.mdはそこをクロスリファレンスする。
• rigor-project-init SKILLを更新し、最初のステップがGemfileの編集ではなくチャンネルの選択になるようにする。

スライス2 — flake packages / appsアウトプット

• packages.default（Rigorをderivation、クロージャ内にRuby 4.0）とapps.rigorをflake.nixに追加する。
• nix run github:rigortype/rigor -- checkとnix profile installの両方が動作する。

スライス3 — CIワークフローテンプレート

• スタンドアロンの.github/workflows/rigor.ymlテンプレートを作成する — 独立したジョブでRigorを実行：actions/checkout、ruby/setup-ruby（Ruby 4.0）、Rigorのインストール、rigor check。
• 両方のピン留め形式を提供：CI専用の.github/rigor/Gemfileと対応するDependabot設定スニペット（デフォルト）、固定されたgem install（最小構成バリアント）。
• ruby/setup-rubyが事前ビルドされたRuby 4.0を公開しているかを検証；まだの場合は、一時的な遅いビルド期間とNix代替手段を文書化する。
• ハーメチックなクロージャを必要とするチームのためのNix代替CIパスを文書化する（スライス2のflakeアウトプットを消費）。

スライス4 — コンテナイメージ

• Dockerfileを追加し、rigorをエントリーポイントとしてRuby 4.0を組み込んだイメージを公開する。

スライス5 — シングルバイナリスパイク（未確定）

• ビルドマトリクスにコミットする前に、Ruby 4.0におけるtebakoと軽量なホームグロウンパッケージングを評価する。

参照

• ADR-0 — このADRの配布モデルが支えるゼロランタイム依存関係・pure Ruby・CLIファーストの立場。
• ADR-19 — Language Serverはrigortype gemにrigor lspとして同梱される；エディタ統合が起動するPATH上のrigor。
• ADR-25 — Rigorがターゲットプロジェクトのgem RBSをデータとして読み取る方法。これが隔離インストールで何も失われない理由。
• rigortype.gemspec — required_ruby_version = [">= 4.0.0", "< 4.1"]。Gemfileチャンネルを実行不可能にする制約。
• flake.nix — スライス2がpackages / appsで拡張する既存のdevShellsのみのflake。
• README.md §「Installation」 — スライス1が書き直す現在のGemfileファーストのテキスト。
• nix-emacs-ci — CIを対象にしたNixツール配布；WD3で検討され、主要なCIルートとしては採用されなかった。バイナリキャッシュレイヤーはRubyがすでにruby/setup-ruby経由で持っているものだから。
• ruby/setup-ruby — ワークフローテンプレートが構築する事前ビルドRuby CIプロビジョニング。
• Rubyブランチ / メンテナンス状況 — WD7の最新Ruby専用立場の背後にあるサポートウィンドウのコンテキスト。
• アプリケーションのGemfileからRuby開発ツールを除外することの先例：solargraph（慣例的）およびruby-lspの「composed bundle」（明示的）。