Squire

Squire

Squire は、コーディングエージェント向けの透過的なローカル実行・検証レイヤーです。一般的なリポジトリ読み取りをホットな状態に保ち、現在宣言されているワークスペースの状態が検証済みかどうかを継続的に管理します。

エージェントは通常のターミナルコマンドを引き続き使用します。Codex がローカルの読み取り専用コマンドを開始する前に、Squire は現在の状態を確認し、実証済みの mmap 観測結果を再生するか、ハッシュ検証済みの最新ファイルバイト列に対して、小規模で上限の定められた操作を実行します。有効なヒットでは、正確な stdout、stderr、終了ステータスが返されます。ミスはすべて、Codex 本来のネイティブ実行パスに従います。

インストール

curl -fsSL https://raw.githubusercontent.com/reidgoodbar/squire/main/install.sh | bash

インストーラーは、Squire と Squire-Codex のリリースアーカイブが一致していることを検証し、ドライバー、Codex ランタイムヘルパー、ホストネイティブの Squire ランタイムを ~/.local/bin にインストールします。Codex の認証情報や設定は変更しません。対応ホストは、amd64 または arm64 の macOS および Linux です。

インストールを確認します。

squire doctor

必須のドライバー、ヘルパー、ランタイム、ABI コンポーネントのいずれかが不足している場合、doctor はゼロ以外の終了コードを返します。

使用方法

任意のディレクトリから開始できます。

squire codex

これがユーザー向けの手順のすべてです。セットアップコマンド、グローバルなシェルシム、プロンプトの変更、MCP ツール、プリロードの挿入、VM のプロビジョニングは必要ありません。Codex が後からリポジトリに移動した場合、Squire はコマンドの実際の cwd からそのリポジトリを検出して準備します。

squire-codex も、直接実行できる便利なコマンドとしてインストールされます。

現在のリポジトリとランタイムを調べます。

squire status
squire status --json
squire explain -- git status --short

継続的な検証

Squire Green は、リポジトリの編集が落ち着いた後、宣言済みのテスト、lint、型チェック、ビルドをバックグラウンドでネイティブに実行します。各結果は、宣言済みの入力バイト列、チェック設定、環境、実行可能ファイルの正確な内容に紐づけられます。その後、関連する編集が行われると結果は古くなりますが、無関係な編集では古くなりません。

# .squire/checks.toml
[[check]]
name = "tests"
command = ["go", "test", "./..."]
inputs = ["**/*.go", "go.mod", "go.sum"]
timeout = "10m"

リポジトリが提供するコマンドは、初回使用時に黙って実行されることはありません。ファイルを確認し、その正確なハッシュを一度信頼します。

squire green trust
squire verify

設定を変更すると、信頼はすべて無効になります。squire codex はその後、信頼済みのチェックを自動的にスケジュールします。2 つ目のデーモンやウォームアップ用コマンドは必要ありません。設定と証明の仕様については、docs/GREEN.md を参照してください。

高速化の対象

本番用の処理経路には上限がありますが、一般的な読み取り専用コマンドはカバーしています。

• Git メタデータ：対応する git rev-parse の形式とブランチの検出。
• リポジトリの読み取り：対応する git status、git ls-files、git diff の形式。パスを指定した diff と git diff --check、および上限付きの git log -N --oneline -- <literal paths> による履歴を含みます。
• ファイルおよび検索の読み取り：上限付きの cat、順序を維持する単一または複数範囲の sed -n、head、tail、nl -ba、file、固定文字列による grep／rg、要求に応じて準備される上限付きのリポジトリ内 rg 検索、制約の厳しい ls 形式。
• 環境の検出：対応するバージョン確認、which／command -v、安全な printenv、whoami、id、hostname、uname の形式。
• 組み合わせ：対応するソースとフィルターを使用する、読み取り専用の完全なプラン。パイプ、シーケンス、/dev/null へのリダイレクト、head、tail、上限付きの sed -n、grep -F、wc -l、sort を含みます。

操作が取り除かれることはありません。ビルド、テスト、編集、インストール、Git を変更するコマンド、展開、未知のシェル構文、機密性の高い確認、未対応の形式は、ただちに変更されていない Codex 本来のネイティブパスに従います。安全なコールドミスの場合も同様にネイティブパスを実行しながら、バックグラウンドで正確な準備を要求します。rg --files は上限付き準備ポリシーの対象外のまま、ネイティブパスに従います。

対応コマンドは、コマンドの完全一致テンプレートではなく、型付きの上限付きプランにコンパイルされます。ソースの証明と実行は別々に行われます。1 つのファイルスナップショットの証明を、異なる行の選択、フィルター、組み合わせに利用でき、コマンド文字列ごとにキャッシュエントリーを作成する必要はありません。同じプラン表現を Go エンジンとネイティブランタイムで実装しているため、今後の読み取り演算子を追加しやすく、差分テストで ABI 境界の同等性を検証できます。

ヒットが最新である理由

Squire がキャッシュするのは観測結果であり、信頼性ではありません。フォアグラウンドでの再実行では、そのコマンドに影響し得る入力を再計算するか、完全な kqueue/inotify ガードが依存関係の変更なしを報告している間、暗号学的フィンガープリントを再利用します。準備済みのエポックも一致している必要があります。証明の入力には、正規化されたコマンドと cwd、Git の refs/index/config と外部の動作ファイル、関連するワークスペースの状態、正規パス、コンテンツハッシュ、コマンド固有の環境証明、実行ファイルの識別情報が含まれます。ガードに失敗した場合、常駐する証明は常に無効化されます。

読み取りサイズが制限されたファイルでは、エポックが一致しない場合に、代わりに現在のファイル用レーンを使用できます。Squire は、フォアグラウンドの SHA-256 証明を計算する際に読み取った正確なバイト列を保持し、そのバイト列に対して固定のバイト文法のみを適用します。再ウォームは不要で、ファイルも結果も永続化されません。キャッシュには古いレコードが残っている可能性がありますが、証明が一致しない場合、それらが再利用されることはありません。状態の欠落、破損、未対応の構文、ABI の不一致、または採算の取れない証明は、すべてネイティブへのフォールバックとなります。

無効化テストスイートでは、サイズや mtime を変えずにファイルのバイト列を変更し、Git のインデックスと未追跡ファイルのセットを変更し、サイズが同じ diff を変更し、Git の設定を編集し、コミットを作成し、ブランチ名を変更し、loose および packed のオブジェクト名前空間を変更し、環境入力を変更し、ワークスペース外を指すシンボリックリンクを検査します。古いバイト列を返す、または安全でないヒットが発生すると、リリースは失敗となります。

不変条件の全容については、SQUIRE_CONTRACT.md を参照してください。

現在のランタイム検証

2026 年 7 月 16 日、500 コマンドによる本番 ABI のランダム実行では、正確なヒットが 421 件、安全なフォールバックが 79 件、ネイティブとの比較が 468 件記録され、不一致はゼロ、安全でないヒットもゼロでした。ヒット時の p50/p95/p99 は 0.315/0.630/0.933ms でした。同じコマンドをネイティブで実行した場合は 8.084/27.692/51.820ms でした。別途実施した 500 クエリのリポジトリ検索差分テストでは、500 件すべてが正確なヒット、または順序が同等のヒットとなり、意味上の不一致はゼロでした。読み取りサイズが制限されたパス履歴は 28/28 件が正確で、p50 が 0.333ms、p99 が 0.492ms でした。ネイティブ実行の p50 は 20.060ms でした。定常状態での 2,048 回の呼び出しはすべて正確で、wall p99 は 0.433ms でした。8 並列負荷では CPU p99 は 0.334ms、スケジューラー競合時の wall p99 は 3.242ms でした。

新たに実施した gpt-5.6-luna のライブ処理では、Express の呼び出し 3 件中 2 件（66.7%）、Flask の呼び出し 5 件中 5 件（100%）、fmt の呼び出し 5 件中 4 件（80%）が個別に再実行されました。すべての処理で、正確な集計と診断上の不一致ゼロを満たし、全終端呼び出しの 50% ゲートを通過しました。こうした少数のライブサンプルで検証できるのはカバレッジであり、タスク全体の所要時間に対する因果効果ではありません。ツールの結果を確認する前に、モデルの実行経路が分岐しました。

決定論的な 40 ペアの Codex 帰属テストでは、モデルの応答、コマンド、ワークスペース、ターミナルのペイロードを固定しました。6 回の逐次呼び出しは 374.876ms から 103.600ms に短縮し、271.277ms（72.4%、ペアの 95% 区間 265.630-276.540ms）を削減しました。2 つの並列バッチでは 52.6% 削減しました。AB と BA の順序ではどちらも正の効果が維持されましたが、A/A と B/B を交互に実施した場合の区間にはゼロが含まれていました。

手法と過去の表の全容については、docs/BENCHMARKS.md を参照してください。

アーキテクチャとバックエンドに関する説明については、docs/ADVANCED.md を参照してください。